API overview

​

Choose the right API endpoint

• Europe (default): https://api.voucherify.io
• United States: https://us1.api.voucherify.io
• Asia (Singapore): https://as1.api.voucherify.io

​

Understand request processing

• Synchronous phase — main response (for example, redemption result).
• Asynchronous phase — background tasks such as:
  • Updating segments
  • Sending webhooks
  • Applying loyalty points
  • Triggering distributions

• Bulk imports or exports (customers, products, vouchers)
• Campaign creation or updates
• Metadata updates

​

Improve performance and efficiency

​

Use efficient API flows

​

Synchronize data when really needed

​

Replace polling with webhooks

​

Client-side API (browser and mobile)

​

SDK and widgets

• Validation
• Redemption
• Voucher publication
• Subscription forms

​

Rate limiting

{
  "code": 429,
  "message": "Too many requests hit the API too quickly."
}

​

Client-side settings

• Allowed website URLs — list allowed origins. Use * only in development.
• Danger zone options — enable with caution to allow the following directly from a client-side API or SDK:
  • Redeeming vouchers (risk: users may change request data)
  • Publishing vouchers
  • Listing vouchers
  • Creating customers (risk: it can expose customer metadata creation to the browser)
  • Updating voucher expiration (recommended only for controlled test cases)
  • Creating loyalty or referral events

​

Manage API versions

​

Backward-compatible changes

• Add new endpoints or properties
• Add optional parameters
• Change property order
• Change the length or format of object IDs or other opaque strings
• Introduce new webhook event types

​

Upgrading

1. Review the API changelog
2. Test the new version in a Sandbox project.
3. Click Upgrade to the latest API version when ready.

​

API changelog

• v2017-04-05 (deprecated):
  • Responses from the voucher and campaign listing methods were moved to the new object structure. Methods now render specific properties for a total count and an array of objects.
  • Introduced validation for listing parameters: limit and page. A limit can range between 1 and 100 items.
  • GET voucher/campaign methods render validation rules related to the voucher object (can be inherited from a campaign).
  • Created an API method for getting a campaign identified by name.
• v2017-04-20 (deprecated):
  • Response from the voucher publish method was moved to the new object structure. Returned voucher details are wrapped by a transaction object describing the publication event:
  Copy

  Ask AI

  {
      "id": "pub_whQzIndYoyZoqiLEKN0s04GK",
      "object": "publication",
      "created_at": "2017-04-20T13:18:01Z",
      "customer_id": "cust_mOjhGypfbqch0v3DpAA9LDXj",
      "tracking_id": "janusz",
      "channel": "API",
      "metadata": {
        "test": true
      },
      "voucher": {}
    }
  

• v2018-08-01: Introduces a new model for building Validation Rules. The extended mechanism provides advanced configuration for promo conditions. Changes affect these API methods:
  • List Promotion Tiers: replaced an object describing conditions by a list of records describing an association between rule and tier (validation_rule_assignments).
  • List Promotion Tiers for campaign: same as above.
  • Promotion Tier Object: updated to support new structure.
  • Validation Rule Object: reorganized to handle advanced rules.
  • Validation Rule Assignment Object: added to describe relation between rules and linked promotions.
  • Validation Rules: modified data model.
• Webhooks v2024-01-01: In v20231205, a new version of webhooks was introduced. These webhooks are available for distribution and the events listed in Project settings.