status. This page maps each value to the action it calls for, and covers the operations that move a resource from one value to the next.
Enrollment
External cards require hosted card entry. Follow
nextAction.url and read the enrollment again to confirm ACTIVE. Show your terms of service and privacy policy before you store the card, as Consent and terms describes.
Revoke an enrollment
Revoke a stored card withPOST /agentic/enrollments/:id/revoke when the user removes it or when the card should stop working.
Response (relevant fields)
ACTIVE enrollment can be revoked. Any other status returns ENROLLMENT_NOT_ACTIVE.
Mandate
CANCELLED and REVOKED are both end states, and neither returns to ACTIVE. The difference is scope. Canceling ends one mandate and leaves the stored card ready for a new one. Revoking the enrollment stops every mandate that points at that card. CONSUMED, EXPIRED, and FAILED are also final, and each one calls for a new mandate.
Reap works out CONSUMED each time you read the mandate. A charge that is still in progress already counts against the budget, so the mandate can read CONSUMED before its last checkout completes. When the mandate was also canceled, revoked, or has expired, you see that status instead.
List mandates
GET /agentic/mandates lists the mandates of one owner. ownerId is required, because every list is scoped to a single owner, and ownerType defaults to CLIENT_REFERENCE. Narrow the list with enrollmentId, or with status, a comma-separated list that defaults to ACTIVE. Pass ACTIVE,PAUSED to include paused mandates.
Response (relevant fields)
nextCursor when it holds a value. A null cursor means the last page.
Pause a mandate
POST /agentic/mandates/:id/pause holds charges and keeps the approved mandate.
Response (relevant fields)
Resume a mandate
POST /agentic/mandates/:id/resume returns status as ACTIVE with the same mandate. Resuming needs no further approval from the user, because nothing about the mandate changed.
Response (relevant fields)
Cancel a mandate
POST /agentic/mandates/:id/cancel returns status as CANCELLED. The enrollment stays untouched and remains available for a new purchase.
Response (relevant fields)
REVOKED rather than CANCELLED.
Quote
A quote has no status field. It has an expiry instead.- Read
expiresAton every quote and open the checkout before that time - Create a new quote with
POST /agentic/quotesonce the expiry has passed, because merchant prices can move in between - Read the quote at any time with
GET /agentic/quotes/:idto get the current total
QUOTE_EXPIRED, and a shipping option change that the merchant can no longer apply returns QUOTE_REPLACEMENT_REQUIRED. Both mean the same thing: create a new quote.
Checkout
COMPLETED, FAILED, and EXPIRED are final. A checkout never leaves one of them, so branch on the status value rather than treating anything other than COMPLETED as still in flight. Neither FAILED nor EXPIRED can be retried in place, and both need a fresh quote and a fresh checkout.
POST /agentic/checkouts returns a nextAction when the charge needs approval. A checkout created under a mandate the user approved earlier skips that step and moves straight into PROCESSING. Whenever the user has to approve, show your terms of service and privacy policy first, whatever surface the user approves from. Consent and terms covers the rule.
A checkout paid through a mandate carries its mandateId, and a hosted checkout returns null there. A failed checkout carries failureReason with a code and a message.
Read the checkout with GET /agentic/checkouts/:id after the user lands back on your return URL. Returning to that URL does not by itself mean the order is placed, so read the status. A nextAction of null on a completed checkout means you have nothing left to do.
Status change events
Reap sends a webhook when an enrollment or a checkout reaches one of the statuses below, so you learn the outcome of a hosted step without reading the resource again. Thedata of each event matches the response of the matching GET endpoint.
A checkout that ends in
FAILED sends no event. While a checkout reports PROCESSING, read it again with GET /agentic/checkouts/:id until it reports a final status or the webhook arrives.Next steps
One-Time Purchases
The full purchase sequence with requests and responses.
FAQ
Short answers to common integration questions.