Objects

The shapes the API returns, described once.

Amounts are integer minor units (cents) — 49999 is $499.99. Timestamps are ISO 8601; fields ending _date are dates.

Checkout Session

Returned by Open a session — the merchant's view, carrying everything your backend needs to file the order and send the customer on.

Field	Type	Notes
id	string	The session's public token, cs_ and 32 characters.
status	enum
order_reference	string	Your own identifier, as sent when the session was opened.
total_amount	integer	The order total the session was quoted against, in cents.
down_payment_amount	integer	Collected at checkout. Snapshotted when the session opened.
down_payment_percentage	integer
checkout_url	string	Where to send the customer.
return_url	string
cancel_url	string
expires_at	timestamp	When the session lapses if nobody acts on it.
created_at	timestamp
metadata	object	Your own key/value pairs, as sent when the session was opened. {} when none were sent.

Contract

A layaway agreement as your server sees it, returned by the contract endpoints. Identified by reference — the same value webhook payloads carry — never by a row id.

Field	Type	Notes
reference	string	The agreement's public reference, e.g. LAY-8F2KQ0MZXA.
order_reference	string or null	Your own identifier, as sent when the session was opened or edited since.
status	enum
customer_name	string
customer_email	string
customer_state	string or null	The two-letter state the agreement was opened against.
total_amount	integer	The order total before the fee.
reservation_fee_amount	integer	The Reservation Fee, retained on default.
customer_total	integer	The order total plus the fee — what the plan collects in all.
down_payment_amount	integer	Collected at checkout.
paid_amount	integer
remaining_amount	integer
installments	array of Plan Installment	The full schedule.
started_at	timestamp or null
completed_at	timestamp or null
defaulted_at	timestamp or null
cancelled_at	timestamp or null
created_at	timestamp
metadata	object	Your own key/value pairs. {} when none were sent.

Plan Installment

One capture on the schedule.

Field	Type	Notes
sequence	integer	The row's position. 1 is the Cart Capture, due immediately.
type	enum
installment_number	integer or null	The Installment Capture's number within the plan, from 1. Null on the Cart Capture.
amount	integer
due_date	date
status	enum
paid_at	timestamp or null	Null until it settles.

Entries after the first fall a fortnight apart, and the amounts sum to customer_total exactly — the final one absorbs the rounding.

Vocabulary

Term	Means
Cart Capture	The opening payment on a plan, taken at checkout. A failure is a failed checkout — no grace period, no late charge, no plan.
Installment Capture	Every capture ShotPay initiates after the Cart Capture, numbered within the plan from 1. The only place the failed-payment timeline applies.
Attempt	One presentment of an Installment Capture, numbered within it. Attempt 1 on the due date, one automated Attempt 2, then a consumer's own "Pay now" is Attempt 3. Never used on the Cart Capture.
Grace Period	Two days from the failure notification (T₀) with no late charge.
Cure Period	Eight further days in which the plan stays recoverable, ending in default.

Layaway Availability

Whether layaway can be offered, and why not when it cannot. Returned inside ping and config.

Field	Type	Notes
available	boolean
reason	enum or null	Null when available.
message	string or null	A customer-safe explanation. Null when available.

Enums

Checkout Session Status

Value	Means
pending	Open, waiting on the customer.
decision_made	Accepted; the agreement is being opened.
completed	Done. The plan exists and the down payment landed.
cancelled	Abandoned. The customer left the checkout without a plan.
expired	Lapsed before anyone acted.

pending may become decision_made, cancelled or expired. decision_made may become completed or cancelled. The last three are terminal, and only a pending session expires.

completed, cancelled and expired are the three a store branches on — each one raises its own event and appears as status on the redirect back. See How your store finds out.

Capture Type

Value	Means
cart_capture	The opening payment, taken at checkout.
installment_capture	A capture ShotPay initiates on the schedule after it.

Contract Status

Value	Means
pending	Opened, but the Cart Capture has not landed. The customer may retry with another method; the agreement lapses with its session otherwise.
active	Running.
completed	Every capture settled.
cancelled	Ended early. What was paid is refunded less the restocking fee; the reservation fee is retained.
defaulted	Ended unpaid after the grace and cure periods. Refunded the same way.

All three resolutions are terminal.

Installment Status

Value	Means
upcoming	Not yet due.
due	Its deadline has passed and it is being collected.
paid	Settled.
past_due	Attempt 2 failed and the consumer was notified — T₀. The two-day grace period is running. Can still be settled.
delinquent	The grace period ran out; the late charge is assessed and the plan defaults at the end of the cure period. Can still be settled.

Block Reason

Why layaway is unavailable. See Error Handling for what to do about each.

Value	Means
platform_disabled	Layaway is off across the platform. Temporary.
merchant_overridden	Layaway is switched off for this account by ShotPay.
state_unavailable	Layaway is not offered in the customer's state.
state_excluded	The program excludes the customer's state outright; no operator can enable it.
merchant_disabled	The merchant has not turned layaway on in their settings.
merchant_inactive	The account is not cleared to transact in this mode.

Mode

Value	Means
sandbox	Simulated payments. Issued against an sk_test_ key.
live	Real money. Issued against an sk_live_ key.

Decided by the key prefix rather than by anything in the request — see Sandbox.