Retrieve a purchase

Retrieve a purchase

You may use this endpoint to poll pending purchases when you expect them to complete.

GET /purchases/{purchase_id}

Error

A valid request URL is required to generate request examples

200

{
  "id": "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c",
  "offering_id": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
  "onetime_offering_id": "onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
  "purchased_at": "2025-01-01T12:00:00Z",
  "completed_at": "2025-01-01T12:00:00Z",
  "description": "<string>",
  "price": {
    "amount": 123,
    "currency": {
      "code": "<string>",
      "name": "<string>",
      "symbol": "<string>",
      "base_unit": 123
    }
  },
  "metadata": {},
  "entitlement_status": {
    "content_key": "<string>",
    "has_entitlement": true,
    "expires": "2023-11-07T05:31:56Z",
    "recurs_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "Invalid authentication credentials",
    "code": "invalid_credentials"
  }
}

{
  "error": {
    "message": "The Bearer token does not match the x-supertab-client-id header | Missing or invalid x-supertab-client-id | Invalid subject type {request_subject_type} found, {expected_token_type} expected | Forbidden",
    "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | forbidden"
  }
}

{
  "error": {
    "message": "Purchase not found",
    "code": "purchase_not_found"
  }
}

{
  "error": [
    {
      "code": "validation_error",
      "message": "Validation Error",
      "errors": [
        {
          "attribute": "query -> subject",
          "code": "missing",
          "message": "field required"
        }
      ]
    }
  ]
}

Required Scopes

capi:read - Read access to Customer API resources

Authorizations

Authorization · string · header · required

Supertab OAuth2 flow for CAPI. See Authentication.

Headers

x-api-version · string<date> · default: 9999-01-01

The version of the Customer API you are using.

x-supertab-client-id · string<tagged_id> · required

Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase.

Examples:

"live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

"test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

Path Parameters

purchase_id · string<tagged_id> · required

An ID of a Purchase

Example:

"purchase.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

Response

200

application/json

Successful Response

id · string<tagged_id> | null · required

When a Purchase has been made with you, shows the ID of the Purchase. Otherwise obfuscated and is shown as null.

Example:

"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"

offering_id · string<tagged_id> | null · required

Which offering was purchased, if this purchase resulted from purchasing a pre-defined offering.

Example:

"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

onetime_offering_id · string<tagged_id> | null · required

Which one-time offering was purchased, if this purchase resulted from purchasing a one-time offering.

Example:

"onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

purchased_at · string<date-time> | null · required

The time the purchase completed.

Example:

"2025-01-01T12:00:00Z"

completed_at · string<date-time> | null · required

The time the purchase completed.

Where Supertab requires a payment this will be null until the payment completes.

Example:

"2025-01-01T12:00:00Z"

description · string · required

A summary of the purchase, usually including the website name and the type of a given entitlement.

Examples:

"The Leek - 24 Hours Time Pass"

"1 Month Subscription"

price · Price · object · required

An amount of money

Show child attributes

status · enum<string> · required

The status of the purchase.

Purchases may be pending or completed.

Only completed purchases grant access, pending purchases are purchases which require payment before entitlement is granted

Available options: completed, pending, abandoned

metadata · Metadata · object · required

Freeform metadata associated with the purchase.

This can be used for e.g associating the purchase with a user identifier in your system

Show child attributes

entitlement_status · EntitlementStatus · object | null · required

The customer's access (if any) as a result of this purchase

Show child attributes