Server API.

Authentication

Create a key under API keys → Secret API keys in the panel. It is shown once; RevFox stores only its hash. Send it as a bearer token to your API server, the api_url the SDKs use:

curl https://api.example.com/v1/customers/user_123 \
  -H "Authorization: Bearer sk_..."

The key decides the project, so URLs carry no project ID. Customer IDs in paths must be URL-encoded, for example %24RCAnonymousID%3Aabc. Any of a customer's aliases finds them.

The customer object

Every endpoint except delete answers with the customer as it is after the change:

{
  "customer": {
    "customer_id": "user_123",
    "original_customer_id": "user_123",
    "aliases": ["user_123", "$RCAnonymousID:abc"],
    "first_seen_at_ms": 1700000000000,
    "last_seen_at_ms": 1760000000000,
    "attributes": {
      "$email": { "value": "[email protected]", "updated_at_ms": 1760000000000 }
    },
    "benefits": ["premium"],
    "purchases": [
      {
        "id": "2000000123",
        "store": "APP_STORE",
        "environment": "PRODUCTION",
        "product_id": "pro.monthly",
        "benefits": ["premium"],
        "is_active": true,
        "will_renew": true,
        "expires_at_ms": 1762000000000
      }
    ]
  }
}

Get a customer

GET/v1/customers/{id}

Returns the customer, or 404 when RevFox does not know the ID. Add ?environment=PRODUCTION or ?environment=SANDBOX to read one environment's purchases; both are read by default.

curl "https://api.example.com/v1/customers/user_123?environment=PRODUCTION" \
  -H "Authorization: Bearer sk_..."

Set attributes

POST/v1/customers/{id}/attributes

Sets attributes; null removes one. Creates the customer when RevFox does not know them yet. Body up to 64 KiB.

curl -X POST https://api.example.com/v1/customers/user_123/attributes \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"attributes": {"$email": "[email protected]", "plan": "team", "referrer": null}}'

Answers 200 with the customer, or 400 when attributes is empty or has an empty key.

Grant a benefit

POST/v1/customers/{id}/grants

Gives the customer a benefit without a store purchase, for a duration or until a time.

curl -X POST https://api.example.com/v1/customers/user_123/grants \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"benefit": "premium", "duration": "monthly"}'

# or until a set time
  -d '{"benefit": "premium", "expires_at_ms": 1762000000000}'

Answers 201 with the customer, or 400 for an unknown benefit or a bad duration. Grants add no revenue, count in every environment and are sent to webhooks. See promotional grants.

Revoke a benefit

DELETE/v1/customers/{id}/grants/{benefit}

Ends the customer's active promotional grants of the benefit. Store purchases are not affected. Answers 200 with the customer, or 404 when there was no active grant.

curl -X DELETE https://api.example.com/v1/customers/user_123/grants/premium \
  -H "Authorization: Bearer sk_..."

Delete a customer

DELETE/v1/customers/{id}

Permanently deletes the customer, their aliases, the purchases they own, their history and grants, for example for a GDPR erasure request. It does not cancel store subscriptions. See deleting a customer.

curl -X DELETE https://api.example.com/v1/customers/user_123 \
  -H "Authorization: Bearer sk_..."

{ "deleted": true, "customer_id": "user_123" }

Errors

Errors are JSON, such as {"error": "customer not found"}. An unexpected server error is answered as plain text.