Ordergroove Developer Documentation

curl -G https://restapi.ordergroove.com/entitlements/ \
     -d external_resource_id=123456 \
     --data-urlencode grantee_external_ids_exact=grantee_a,grantee_b \
     -d merchant=339536244b7c11eb8d37ee71e0f3a639 \
     -d merchant_user_id=23799452926316 \
     --data-urlencode "resource_name=Piano lesson" \
     -d resource_public_id=ecb42bee71ff11efb72ef29e3ec3bb34 \
     --data-urlencode resource_public_ids=ecb42bee71ff11efb72ef29e3ec3bb34,3fa56741671444bdbcdf7b1554f67bee

{
  "next": "https://restapi.ordergroove.com/entitlements/?cursor=NjZmMmExYzRlOGIzZDI3YTljMGY0ZTUxOm5leHQ%3D&merchant=339536244b7c11eb8d37ee71e0f3a639&page_size=100",
  "previous": null,
  "results": [
    {
      "merchant": "339536244b7c11eb8d37ee71e0f3a639",
      "public_id": "4c6dceaa1ddc4361962f9f6b11c0af7a",
      "merchant_user_id": "test_user_id",
      "initial_activation_date": "2024-08-12T20:35:19.04Z",
      "latest_activation_date": "2024-08-12T20:35:19.04Z",
      "grace_period": null,
      "live": false,
      "access_type": "time_based",
      "expiration": "2024-09-12T20:35:19.04Z",
      "created": "2024-08-12T20:35:19.04Z",
      "last_updated": "2024-08-12T20:35:19.04Z",
      "grantees": [
        {
          "external_id": "grantee-001",
          "name": "Alex Rivera",
          "created": "2024-08-12T20:35:19.04Z",
          "updated": "2024-08-12T20:35:19.04Z"
        }
      ],
      "resource": {
        "public_id": "ecb42bee71ff11efb72ef29e3ec3bb34",
        "merchant": "339536244b7c11eb8d37ee71e0f3a639",
        "name": "Piano lesson",
        "external_resource_id": "123456",
        "identified_product_external_id": null,
        "description": null,
        "image_url": "https://example.com/images/piano-lesson.png",
        "created": "2024-08-01T14:02:11.512Z",
        "last_updated": "2024-08-01T14:02:11.512Z"
      }
    }
  ]
}

Returns a paginated list of entitlements for a merchant’s customers, newest first. Only relevant for merchants offering digital products.

Query parameters narrow the results, and combining them returns only entitlements that match all of them. With Storefront API Scope authentication, only the authenticated customer’s entitlements are returned and merchant_user_id is ignored.

Results are cursor-paginated. To page through them, follow the next and previous URLs in the response.

Accepts Application API Scope or Storefront API Scope authentication.

Query parameters

merchantstringRequired

Merchant ID. Must match the merchant the credentials belong to. A missing or mismatched value returns 403.

merchant_user_idstringOptional

Customer ID. Returns only this customer's entitlements. Ignored with Storefront API Scope, which always returns only the authenticated customer's entitlements.

resource_public_idstringOptional

Returns only entitlements for this resource ID. Cannot be combined with resource_public_ids.

resource_public_idsstringOptional

Returns only entitlements for any of these resource IDs. Provide a comma-separated list of up to 50 IDs, with no duplicates or empty values. Cannot be combined with resource_public_id.

external_resource_idstringOptional

Returns only entitlements for the resource with this merchant resource ID (the resource’s external_resource_id). Returns an empty list if no resource matches.

resource_namestringOptional

Returns only entitlements for resources whose name exactly matches this value, ignoring case and leading or trailing whitespace. Returns an empty list if no resource matches.

livebooleanOptional

true returns only entitlements that are currently live, meaning their expiration plus any grace_period hasn’t passed. false returns only entitlements that are no longer live.

has_granteesbooleanOptional

true returns only entitlements with at least one grantee. false returns only entitlements with no grantees. Cannot be combined with grantee_external_ids_exact.

grantee_external_ids_exactstringOptional

Returns only entitlements whose grantees are exactly this set of grantee external IDs, in any order. Provide a comma-separated list of up to 50 IDs, with no duplicates or empty values. For example, grantee_a,grantee_b matches an entitlement with grantees grantee_a and grantee_b, but not one with only grantee_a or one that also has grantee_c. Cannot be combined with has_grantees.

page_sizeintegerOptional1-100Defaults to 100

Number of entitlements to return per page, from 1 to 100.

cursorstringOptional

Position to continue paginating from. Set automatically in the next and previous URLs; don’t construct it yourself.

Response

200

nextstring or null

URL to get the next page of results. null if there are no more pages.

previousstring or null

URL to get the previous page of results. null if there are no previous pages.

resultslist of objects

Up to page_size entitlements (100 by default), newest first.

Errors

400

Bad Request Error

403

Forbidden Error

500

Internal Server Error