Skip to main content
Every agentic resource reports a 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 with POST /agentic/enrollments/:id/revoke when the user removes it or when the card should stop working.
Response (relevant fields)
See the revoke enrollment reference for the full response. Only an ACTIVE enrollment can be revoked. Any other status returns ENROLLMENT_NOT_ACTIVE.
Revoking is final. You cannot charge or restore a revoked enrollment. You will need to create a new enrollment to use the same card.

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)
See the list mandates reference for the full response. Follow 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)
See the pause mandate reference for the full response.

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)
See the resume mandate reference for the full response.

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)
See the cancel mandate reference for the full response. Pause and resume suit a temporary hold. Cancel ends the mandate for good. Revoking the enrollment is the wider action, because it stops charges across every mandate that points at the same stored card, and those mandates report REVOKED rather than CANCELLED.

Quote

A quote has no status field. It has an expiry instead.
  • Read expiresAt on every quote and open the checkout before that time
  • Create a new quote with POST /agentic/quotes once the expiry has passed, because merchant prices can move in between
  • Read the quote at any time with GET /agentic/quotes/:id to get the current total
A call that reaches an expired quote returns 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. The data 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.