Skip to main content
POST

Authorizations

Authorization
string
header
required

Bearer credential for the public API: a live COPE API key (ck_live_*; keys issued earlier as cope_sk_live_* keep working). Dashboard sign-in tokens are not accepted.

Headers

Idempotency-Key
string
required

Required. At most 255 characters of valid UTF-8 with no NUL byte. A retry that carries the same key and the same body returns the original response instead of performing the write a second time. The same key with a different body is refused with 409 idempotency_conflict. Keys are remembered for 24 hours. A returned original response carries the header Idempotent-Replayed: true.

Maximum string length: 255

Body

application/json
buyer
object
required
currency
string
required

Currency of the offer, as an ISO 4217 code. It must be one the seller can be paid in: a currency COPE charges in that is also the currency of one of the seller's payout bank accounts. The currencies of the product's own payment plans are not considered. Anything else is refused with 422 validation_failed, errors[].param pricing.currency, naming the currencies the seller can use.

Pattern: ^[A-Z]{3}$
pricing
object
required

Shape and amounts of the payment. plan_type decides which of the fields below you have to send: one_time needs nothing beyond price_minor_units; subscription also needs recurring_amount_minor_units, interval and interval_count; installment needs those three and installment_count as well. Every other field here is optional under all three.

product_id
string
required

Product the offer sells. It must belong to the seller the token is issued for; any other product answers 404.

Pattern: ^prod_[A-Za-z0-9]{8,32}$
Example:

"prod_A1b2C3d4"

embed_origin
string

Origin allowed to frame this offer's checkout, so the buyer can pay inside your own page instead of following the redirect. It must be one you have already registered and enabled for checkout embedding; anything else — including an origin another seller registered — is refused with 422 embed_origin_not_allowed and no offer is created. Omit it for a redirect-only offer.

Pattern: ^https://[^@/?#\s]+$
external_reference
string

Your own reference for this sale — a customer, deal or quote id. It is returned on the offer and arrives on every order and payment webhook for the order the offer becomes, as metadata.external_reference. A blank value is refused.

Required string length: 1 - 255

Omit the object entirely to issue a link that never expires.

metadata
object

Your own key-value data for this sale. It is returned on the offer and arrives on every order and payment webhook for the order the offer becomes, as metadata, beside external_reference. At most 50 entries at any level, 4 levels of nesting, keys of up to 64 characters, and 8 KB as JSON with external_reference included; anything larger is refused with 422 validation_failed. external_reference and the keys COPE uses itself (intended_payment_method, authority_kind, clerk_user_id, event_sales_session_id, seller_device_id) are refused inside it.

quantity
integer
default:1

Units of the product on the offer. More than 1 only when the product lets a buyer choose a quantity, and then up to its own maximum; anything else is refused with 422 quantity_not_allowed.

Required range: 1 <= x <= 1000

Response

Successful response

data
object
required