Create an offer
Prices one product for one named buyer and returns a private checkout link made out to
them. The price, the quantity and the buyer are settled here and are read-only on the
offer page, so everything the order will need has to be supplied in this request. The
offer accepts the payment methods the product already accepts; they cannot be chosen per
offer. Creating an offer does not notify the buyer — the link comes back as public_url
and is yours to send.
Choosing a payment plan
pricing.plan_type decides the rest of the body. Send the fields its row asks for;
every other field under pricing is optional under all three plan types.
plan_type | What the buyer is charged | Send alongside plan_type and price_minor_units |
|---|---|---|
one_time | price_minor_units, once. | nothing |
subscription | price_minor_units now, then recurring_amount_minor_units every billing period until the subscription is cancelled. | recurring_amount_minor_units, interval, interval_count |
installment | price_minor_units now, then recurring_amount_minor_units every billing period until installment_count payments have been made in total, counting the first. | recurring_amount_minor_units, interval, interval_count, installment_count |
The billing period is interval × interval_count — month × 3 bills quarterly — and a
single period may not be longer than two years. second_payment_in, trial_days,
shipping_price_minor_units and custom_plan_name stay optional under every plan type.
installment is accepted only from sellers enabled for installment sales; one_time and
subscription are open to every seller.
Opening the offer inside your own page
By default the buyer follows public_url, which redirects them to the offer’s checkout on
COPE. Send embed_origin instead and the same checkout can be framed in your own page:
the offer comes back with an embed_url and embed_origin echoing the one origin allowed
to frame it. Both are absent — not null — on an offer that cannot be framed, and
public_url keeps working either way.
Hand both to the Checkout SDK’s mountCheckout rather
than building the iframe yourself: the framed page waits for a mount handshake from its
parent before it starts, so a bare <iframe src=embed_url> never loads.
embed_origin must be an origin you have already registered and enabled for checkout
embedding. An origin you have not registered, one another seller registered, and one that
has been disabled or archived are each refused with 422 embed_origin_not_allowed, and no
offer is created. Disabling or archiving the origin afterwards stops every offer embed
bound to it.
Authorizations
Bearer credential for the public API. Vendor integrations should send a live COPE API key (cope_sk_live_*). Clerk bearer tokens are also accepted when paired with X-Cope-Business-Id.
Headers
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.
255Body
Show child attributes
Show child attributes
Currency of the offer, as an ISO 4217 code. It must be one the seller can be paid in — anything else is refused with a 422 naming the ones they can.
^[A-Z]{3}$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.
Show child attributes
Show child attributes
Product the offer sells. It must belong to the seller the token is issued for; any other product answers 404.
^prod_[A-Za-z0-9]{8}$"prod_A1b2C3d4"
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.
^https://[^@/?#\s]+$Omit the object entirely to issue a link that never expires.
Show child attributes
Show child attributes
Units of the product on the offer. Defaults to 1, and may not exceed 100.
1 <= x <= 100Response
Successful response
Show child attributes
Show child attributes
Was this page helpful?