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.
The body is read exactly as written. A member this reference does not list, at any
depth, is refused with 400 invalid_request rather than ignored, and so is a value of
the wrong JSON type — "24900" is not read as the integer 24900 — and any parameter
sent in the query string. The one member read without being listed is the name the
first edition of this reference gave product_id, still accepted in its place. An
explicit null for any member, at any depth, is read as leaving it out. A body that
names no product_id is a 400 too; 404 means the product named is not one you can sell.
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.
The currency is the one line in the examples below that is not yours to copy: it must be
one the seller can actually be paid in, which means 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. The examples are priced in EUR, and a seller whose payout
accounts are all in USD is refused with 422 validation_failed, errors[].param
pricing.currency, naming the currencies they can use — no offer is created. Send theirs.
Without pricing.trial_days, the buyer gets the product’s own free trial
(trial_period_days), whatever the plan_type, one_time included. Send trial_days: 0
for no trial.
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.
Matching the order to your own records
Send external_reference — your customer, deal or quote id — and any metadata of your
own. Both are returned on the offer, and once the buyer pays, the order the offer becomes
carries them on every order and payment webhook: in metadata on cart.order.created and
cart.order.completed, and in order.metadata on every payment.* event, with
order.source set to offer. The buyer cannot change them on the offer’s checkout.
Identify the order by its id, not by the reference: a checkout link can carry the same
external_reference. Once the offer is paid, retrieving it returns order.id, the order
the payment webhooks name; use external_reference to group that order with your own
record. external_reference is a reserved key: send it as its own member, never inside
metadata, where it is refused with 422 reserved_metadata_key.
Requires the orders permission at write. An API key holds a permission at the lower of its own level (read for a read-only key) and its holder’s role; a key without it is refused with 403.
Authorizations
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. A returned original response carries the header Idempotent-Replayed: true.
255Body
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.
^[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
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]+$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.
Was this page helpful?