Create a canonical offer scoped to one or more plan prices. Currency-specific phases require an explicit USD value and never fall back across currencies.

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Header Parameters

Idempotency-Key?string

Unique key used to safely retry this write for 24 hours without applying it twice.

Length1 <= length <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 200

purpose*string

Value in

"introductory"
"promotional"

planPriceIds*array<>

Items1 <= items

phases*array<|||>

Items1 <= items <= 10

metadata?

Default{}

startsAt?|

Defaultnull

endsAt?|

Defaultnull

active?boolean

Defaulttrue

Response Body

`application/json`

curl -X POST "https://example.com/offers" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "purpose": "introductory",    "planPriceIds": [      "string"    ],    "phases": [      {        "type": "free_trial",        "durationDays": 1      }    ]  }'

{  "id": "string",  "name": "string",  "purpose": "introductory",  "planPriceIds": [    "string"  ],  "phases": [    {      "type": "free_trial",      "durationDays": 1    }  ],  "metadata": {    "property1": null,    "property2": null  },  "startsAt": "2019-08-24T14:15:22Z",  "endsAt": "2019-08-24T14:15:22Z",  "active": true,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "object": "offer",  "livemode": true}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

Create offer

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`