API reference

Promotion Codes

A Promotion Code represents a customer-redeemable code for an underlying promotion. You can create multiple codes for a single promotion. If you enable promotion codes in your customer portal configuration, then customers can redeem a code themselves when updating a subscription in the portal. Customers can also view the currently active promotion codes and coupons on each of their subscriptions in the portal.

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a promotion code

POST/v1/promotion_codes

A promotion code points to an underlying promotion. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.

Body parameters

  • promotionobjectRequired

    The promotion referenced by this promotion code.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • coupon
    • couponstring
  • activeboolean

    Whether the promotion code is currently active.

  • codestring

    The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for a specific customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). If left blank, we will generate one automatically.

  • customerstring

    The customer who can use this promotion code. If not set, all customers can use the promotion code.

  • customer_accountstring

    The account representing the customer who can use this promotion code. If not set, all customers can use the promotion code.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • expires_atinteger

    The timestamp at which this promotion code will expire. If the coupon has specified a redeems_by, then this value cannot be after the coupon's redeems_by.

  • max_redemptionsinteger

    A positive integer specifying the number of times the promotion code can be redeemed. If the coupon has specified a max_redemptions, then this value cannot be greater than the coupon's max_redemptions.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • restrictionsobject

    Settings that restrict the redemption of the promotion code.

    Show 4 child parameters
    • currency_optionsobject
    • first_time_transactionboolean
    • minimum_amountinteger
    • minimum_amount_currencystring

Returns

The promotion_code object.

POST /v1/promotion_codes
curl https://api.knoxapi.com/v1/promotion_codes \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "promotion[type]=coupon"
Response
{
  "active": false,
  "code": "FALL20",
  "created": 1234567890,
  "customer": null,
  "expires_at": 1234567890,
  "id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
  "livemode": false,
  "max_redemptions": null,
  "metadata": {},
  "object": "promotion_code",
  "restrictions": {
    "first_time_transaction": false,
    "minimum_amount": null,
    "minimum_amount_currency": null
  },
  "times_redeemed": 0,
  "promotion": {
    "coupon": null,
    "type": "coupon"
  },
  "customer_account": null
}

List all promotion codes

GET/v1/promotion_codes

Returns a list of your promotion codes.

Query parameters

  • activeboolean

    Filter promotion codes by whether they are active.

  • codestring

    Only return promotion codes that have this case-insensitive code.

  • couponstring

    Only return promotion codes for this coupon.

  • createdobject | integer

    A filter on the list, based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • customerstring

    Only return promotion codes that are restricted to this customer.

  • customer_accountstring

    Only return promotion codes that are restricted to this account representing the customer.

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of promotion_code objects.

GET /v1/promotion_codes
curl -G https://api.knoxapi.com/v1/promotion_codes \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/promotion_codes",
  "has_more": false,
  "data": [
    {
      "active": false,
      "code": "FALL20",
      "created": 1234567890,
      "customer": null,
      "expires_at": 1234567890,
      "id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
      "livemode": false,
      "max_redemptions": null,
      "metadata": {},
      "object": "promotion_code",
      "restrictions": {
        "first_time_transaction": false,
        "minimum_amount": null,
        "minimum_amount_currency": null
      },
      "times_redeemed": 0,
      "promotion": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    }
  ]
}

Update a promotion code

POST/v1/promotion_codes/{promotion_code}

Updates the specified promotion code by setting the values of the parameters passed. Most fields are, by design, not editable.

Path parameters

  • promotion_codestringRequired

Body parameters

  • activeboolean

    Whether the promotion code is currently active. A promotion code can only be reactivated when the coupon is still valid and the promotion code is otherwise redeemable.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • restrictionsobject

    Settings that restrict the redemption of the promotion code.

    Show 1 child parameter
    • currency_optionsobject

Returns

The promotion_code object.

POST /v1/promotion_codes/{promotion_code}
curl https://api.knoxapi.com/v1/promotion_codes/promo_1Pgc79B7WZ01zgkWNy4mn5NX \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "active": false,
  "code": "FALL20",
  "created": 1234567890,
  "customer": null,
  "expires_at": 1234567890,
  "id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
  "livemode": false,
  "max_redemptions": null,
  "metadata": {},
  "object": "promotion_code",
  "restrictions": {
    "first_time_transaction": false,
    "minimum_amount": null,
    "minimum_amount_currency": null
  },
  "times_redeemed": 0,
  "promotion": {
    "coupon": null,
    "type": "coupon"
  },
  "customer_account": null
}

Retrieve a promotion code

GET/v1/promotion_codes/{promotion_code}

Retrieves the promotion code with the given ID. In order to retrieve a promotion code by the customer-facing code use list with the desired code.

Path parameters

  • promotion_codestringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The promotion_code object.

GET /v1/promotion_codes/{promotion_code}
curl https://api.knoxapi.com/v1/promotion_codes/promo_1Pgc79B7WZ01zgkWNy4mn5NX \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "active": false,
  "code": "FALL20",
  "created": 1234567890,
  "customer": null,
  "expires_at": 1234567890,
  "id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
  "livemode": false,
  "max_redemptions": null,
  "metadata": {},
  "object": "promotion_code",
  "restrictions": {
    "first_time_transaction": false,
    "minimum_amount": null,
    "minimum_amount_currency": null
  },
  "times_redeemed": 0,
  "promotion": {
    "coupon": null,
    "type": "coupon"
  },
  "customer_account": null
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.