Getting Started with the Abra API

Last updated: September 29, 2026

The Abra API lets your server manage a store's Abra promotions and discounts, generate unique codes and receive webhooks. This guide covers what you need before you start, how to get an API token and how to make your first request.

Beta. The Abra API is in beta, so its behavior may change. If something doesn't work as described, contact us at help@abrapromotions.com.

What you can do with the API

Use the API from your own server or scripts to:

  • Create, update, publish, deactivate and delete promotions.

  • Create, update and delete discounts.

  • Generate unique codes for a code discount. The codes are added to the discount in Shopify. Get them from the Shopify admin or the Shopify Admin API.

  • Subscribe to webhooks for promotion and discount create, update and delete events.

The API is not for storefronts. Your API token must stay secret, so never call the API from a theme, a headless storefront or a mobile app. To show Abra promotions to shoppers, use one of these instead:

Before you start

  • Abra is installed on the store you want to work with.

  • Each store has its own API token. An integration that works with several stores needs one token for each store.

  • There's no sandbox, and the API is in beta. Every call acts on the live store, and your changes can reach real customers. Build and test on a Shopify development store with Abra installed first.

Get your API token

To create a token:

  1. In the Shopify admin, open the Abra app and go to Settings.

  2. In the API access section, click Generate API token.

  3. Copy the token and store it somewhere safe, such as your server's secret manager. Abra shows the token only once.

About the token:

  • It's valid for 365 days. The API access section shows the date it was created.

  • A store has one active token. If the store already has one, the section shows Regenerate and Revoke instead. Regenerate creates a new token and immediately invalidates the old one, so any integration still using the old token stops working. Revoke invalidates the token without replacing it.

  • It works for one store only, and it can call every endpoint for that store. There are no read-only or limited tokens.

  • Treat it like a password. Keep it on your server, and never put it in browser or storefront code or commit it to source control.

Make your first request

Every request needs an Authorization: Bearer <token> header. The token identifies the store, so you don't pass a store name.

This example lists the store's promotions. Set the base URL and your token once, then run the request:

export ABRA_API_BASE="https://abra-api-333886610689.us-central1.run.app"
export ABRA_API_TOKEN="your-api-token"

curl "$ABRA_API_BASE/v1/partner/promotions?limit=1" \
  -H "Authorization: Bearer $ABRA_API_TOKEN"

A successful call returns 200 OK. The promotions are in data, and pagination describes the page. The response below is shortened. For every field, see The promotion object.

{
  "data": [
    {
      "id": "4f6c2b1e-8a3d-4c5e-9b7f-2d1a0e3c5b6a",
      "title": "Fall Sale 2026",
      "slug": "fall-sale-2026",
      "status": "ACTIVE",
      "visibility": "PUBLIC",
      "startsAt": "2026-09-15T04:00:00.000Z",
      "endsAt": "2026-10-15T03:59:59.000Z",
      "useDiscountDates": true,
      "discounts": [
        {
          "id": "9b2e7d4c-1f3a-4e6b-8c5d-7a0f2e1b3c4d",
          "title": "Spend more save more",
          "discountClass": "PRODUCT",
          "discountValueType": "TieredDiscount",
          "status": "ACTIVE",
          "startsAt": "2026-09-15T04:00:00.000Z",
          "endsAt": "2026-10-15T03:59:59.000Z"
        }
      ],
      "createdAt": "2026-09-10T14:12:09.000Z",
      "updatedAt": "2026-09-12T09:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 3,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

If the store has no promotions yet, data is an empty array. The call still confirms that your token works.

If the token is missing, mistyped, expired or revoked, the API returns 401 with this body:

{
  "error": {
    "code": "UNAUTHORIZED",
    "description": "Invalid or missing authentication"
  }
}

There's no "try it" button in these docs, because browsers can't call the API from other websites. Use curl, Postman or your own server code.

API basics

Base URL. Every path in these docs is relative to the base URL in the example above. See Base URL in the API overview.

Versioning. The API version is part of every path, as in /v1/partner/promotions. Always call the versioned paths shown in these docs. The API overview lists every endpoint with its path.

Rate limits. Limits apply per store, and reads and writes are counted separately. Responses include headers that show how many requests you have left, and a 429 response includes a Retry-After header. See Rate limits in the API overview for the current limits.

Errors. Errors return an HTTP status code and a JSON body with a machine-readable error.code and a readable error.description. Validation errors also list the problem fields in issues. See Errors in the API overview.

Pagination. The promotion and discount lists return one page at a time. Use the page and limit query parameters, and check pagination to see whether there are more pages. See Pagination in the API overview.

Request bodies. Send request bodies as JSON, with a Content-Type: application/json header.

Next steps