# COPE

> COPE developer documentation: the public API, the Checkout SDK, webhooks, and AI agents.

- [COPE developer docs](https://docs.cope.com/index.md): Public COPE developer documentation for checkout SDK integrations, public API usage, and webhook events.
- [Build a vendor integration](https://docs.cope.com/quickstart/build-an-integration.md): End-to-end quickstart for a vendor adding COPE checkout and webhook handling to an existing site, with a reference Next.js sample app.
- [Consume webhooks](https://docs.cope.com/quickstart/consume-webhooks.md): The recommended first steps for receiving and processing COPE webhook events.
- [Public API overview](https://docs.cope.com/api-reference/overview.md): COPE exposes a RESTful public API for vendor integrations. Authenticate with a Bearer API key and call the endpoints described in this reference.
- [Authentication](https://docs.cope.com/api-reference/authentication.md): Use a Bearer API key from the COPE vendor dashboard to authenticate every request.
- [API key integrations](https://docs.cope.com/api-reference/api-key-integrations.md): Create, store, rotate, deactivate, and delete COPE public API keys safely.
- [Errors](https://docs.cope.com/api-reference/errors.md): COPE public API errors use RFC 9457 application/problem+json envelopes with stable codes.
- [Create a checkout](https://docs.cope.com/api-reference/checkouts/create-a-checkout.md): Creates a checkout from your server with its product, plan, buyer email and your reference fixed, and returns its `checkout_url` for you to send the buyer to. On that page the buyer cannot change the email you set; the other details stay theirs to correct. Your `metadata` and `external_reference` ca…
- [Retrieve a checkout](https://docs.cope.com/api-reference/checkouts/retrieve-a-checkout.md): Returns a checkout you created. `order` names the order the buyer's payment made once it succeeded, and is null until then; `status` reads `completed` whenever `order` is set. A checkout expires 30 minutes after it was created.
- [List invoices](https://docs.cope.com/api-reference/invoices/list-invoices.md): Requires the `payments` permission at `read`. 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.
- [Retrieve an invoice](https://docs.cope.com/api-reference/invoices/retrieve-an-invoice.md): Requires the `payments` permission at `read`. 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.
- [List offers](https://docs.cope.com/api-reference/offers/list-offers.md): Requires the `orders` permission at `read`. 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.
- [Create an offer](https://docs.cope.com/api-reference/offers/create-an-offer.md): 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 pro…
- [Retrieve an offer](https://docs.cope.com/api-reference/offers/retrieve-an-offer.md): Requires the `orders` permission at `read`. 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.
- [Cancel an offer](https://docs.cope.com/api-reference/offers/cancel-an-offer.md): Cancels an `active` offer and returns it. The buyer's link stops offering checkout and shows a cancelled offer instead, so a cancelled offer can no longer be paid.
- [Resend an offer to its buyer](https://docs.cope.com/api-reference/offers/resend-an-offer-to-its-buyer.md): Delivers the same private checkout link to the buyer again, and returns the offer. The offer must already have been sent once — use send for the first delivery — and must still be `active` and unlapsed.
- [Send an offer to its buyer](https://docs.cope.com/api-reference/offers/send-an-offer-to-its-buyer.md): Delivers this offer's private checkout link to its buyer for the first time, and returns the offer. Only an `active` offer that has not lapsed and that carries a buyer email and name can be sent.
- [List orders](https://docs.cope.com/api-reference/orders/list-orders.md): Lists the business's orders, newest first. Without `state` only completed (`succeeded`) orders are listed, as before the parameter existed; name `state` to list drafts, pending and failed orders too, each with its `last_payment_error`.
- [Retrieve an order](https://docs.cope.com/api-reference/orders/retrieve-an-order.md): Without `state` only a completed (`succeeded`) order is returned, and any other answers 404, so a 200 still means the order was paid. Name the states you accept (`?state=draft,pending,succeeded,failed`) to retrieve an order in any of them, for example one whose id a `cart.order.created` or `cart.ord…
- [List payments](https://docs.cope.com/api-reference/payments/list-payments.md): Lists the business's succeeded sale payments whose funds availability date is known. A sale appears once the processor reports that date, so a sale whose date is not known yet is not listed and answers 404 on GET /v1/commerce/payments/{id}. Refunds are listed at GET /v1/commerce/refunds; chargebacks…
- [Retrieve a payment](https://docs.cope.com/api-reference/payments/retrieve-a-payment.md): Requires the `payments` permission at `read`. 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.
- [Refund a payment](https://docs.cope.com/api-reference/refunds/refund-a-payment.md): Refunds a settled sale and returns the refund it created. Only a sale can be refunded — passing a refund's own id answers 404, exactly as reading it through `GET /v1/commerce/payments/{id}` does.
- [List refunds](https://docs.cope.com/api-reference/refunds/list-refunds.md): Requires the `payments` permission at `read`. 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.
- [Retrieve a refund](https://docs.cope.com/api-reference/refunds/retrieve-a-refund.md): Requires the `payments` permission at `read`. 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.
- [List products](https://docs.cope.com/api-reference/products/list-products.md): Requires the `products` permission at `read`. 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.
- [Create a product](https://docs.cope.com/api-reference/products/create-a-product.md): A new product starts inactive and in review: it is not on sale until COPE approves it and it is published. A `physical_service` needs `product_location_attributes`. Two concurrent creates that send the same new ship-from address can meet 409 `product_location_conflict`; send the request again.
- [Retrieve a product](https://docs.cope.com/api-reference/products/retrieve-a-product.md): Requires the `products` permission at `read`. 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.
- [Update a product](https://docs.cope.com/api-reference/products/update-a-product.md): Any accepted change, a tags-only one included, takes the product off sale and back to review (`status` inactive, `approval_status` review) until COPE approves it and it is published again. The one exception is an approved product of a business COPE trusts to skip re-review, which keeps its status an…
- [Attach a downloadable file](https://docs.cope.com/api-reference/products/attach-a-downloadable-file.md): Step three of three. A product holds at most 5 downloadable files. The content type is checked again here against the file allow-list. Attaching a file takes the product off sale and back to review (`status` inactive, `approval_status` review) until COPE approves it and it is published again. The on…
- [Attach a product image](https://docs.cope.com/api-reference/products/attach-a-product-image.md): Step three of three. A product holds at most 5 images. The content type is checked again here, so a file uploaded as a document is rejected by this endpoint even though the upload session accepted it. Attaching an image takes the product off sale and back to review (`status` inactive, `approval_stat…
- [Create a media upload session](https://docs.cope.com/api-reference/products/create-a-media-upload-session.md): Step one of three. Returns an upload token and a direct upload URL; send the file bytes to that URL with the returned headers, then attach the token to a product. The URL points at object storage, not at this API. A token is consumed by a successful attach and cannot be reused; a rejected attach lea…
- [List subscriptions changed in a time window](https://docs.cope.com/api-reference/subscriptions/list-subscriptions-changed-in-a-time-window.md): Lists your subscriptions in the order their `updated_at` moved, oldest change first: the feed a reconciliation reads to learn what changed since it last looked. Every subscription whose `updated_at` is in the window `[updated_since, updated_until)` is returned exactly once, however many share one `u…
- [Retrieve a subscription](https://docs.cope.com/api-reference/subscriptions/retrieve-a-subscription.md): Requires the `subscriptions` permission at `read`. 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.
- [Cancel a subscription](https://docs.cope.com/api-reference/subscriptions/cancel-a-subscription.md): Cancels a subscription and returns the subscription. `mode` decides when it ends: `at_period_end` lets the period the buyer has already paid for run out, `immediate` ends it now. A subscription in `trial` can only be cancelled `immediate`.
- [List a subscription's price and plan change attempts](https://docs.cope.com/api-reference/subscriptions/list-a-subscriptions-price-and-plan-change-attempts.md): Every attempt to change this subscription's recurring amount (`price`) or to move it to another plan (`plan`), newest first, whether it was applied or refused. A refused attempt is recorded too and reads `status: failed` with a `failure` saying what stopped it, so an empty list means no amount or pl…
- [Pause a subscription's renewals](https://docs.cope.com/api-reference/subscriptions/pause-a-subscriptions-renewals.md): Stops collecting renewals on an `active` subscription and returns the subscription. There is no end date and no automatic resume: it stays paused until you resume it.
- [Create a payment recovery link](https://docs.cope.com/api-reference/subscriptions/create-a-payment-recovery-link.md): Creates a link the buyer opens, without logging in, to replace the payment method of an **overdue** subscription and pay what is overdue. Send it to the buyer yourself, by any channel. It is the same page COPE's payment-failed email and payment reminders link to.
- [Move a subscription to another plan](https://docs.cope.com/api-reference/subscriptions/move-a-subscription-to-another-plan.md): Requires the `subscriptions` 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.
- [Change a subscription's recurring amount](https://docs.cope.com/api-reference/subscriptions/change-a-subscriptions-recurring-amount.md): Requires the `subscriptions` 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.
- [Resume a paused subscription](https://docs.cope.com/api-reference/subscriptions/resume-a-paused-subscription.md): Starts collecting renewals again on a `paused` subscription and returns the subscription.
- [List webhook deliveries](https://docs.cope.com/api-reference/list-webhook-deliveries.md)
- [Retrieve a webhook delivery](https://docs.cope.com/api-reference/retrieve-a-webhook-delivery.md)
- [Replay a webhook delivery](https://docs.cope.com/api-reference/replay-a-webhook-delivery.md)
- [List webhook endpoints](https://docs.cope.com/api-reference/list-webhook-endpoints.md)
- [Create a webhook endpoint](https://docs.cope.com/api-reference/create-a-webhook-endpoint.md)
- [Retrieve a webhook endpoint](https://docs.cope.com/api-reference/retrieve-a-webhook-endpoint.md)
- [Delete a webhook endpoint](https://docs.cope.com/api-reference/delete-a-webhook-endpoint.md)
- [Update a webhook endpoint](https://docs.cope.com/api-reference/update-a-webhook-endpoint.md)
- [List webhook endpoint event subscriptions](https://docs.cope.com/api-reference/list-webhook-endpoint-event-subscriptions.md)
- [Update webhook endpoint event subscriptions](https://docs.cope.com/api-reference/update-webhook-endpoint-event-subscriptions.md)
- [Rotate a webhook endpoint signing secret](https://docs.cope.com/api-reference/rotate-a-webhook-endpoint-signing-secret.md)
- [Send a test event to a webhook endpoint](https://docs.cope.com/api-reference/send-a-test-event-to-a-webhook-endpoint.md)
- [List public webhook event types](https://docs.cope.com/api-reference/list-public-webhook-event-types.md)
- [Retrieve a public webhook event type](https://docs.cope.com/api-reference/retrieve-a-public-webhook-event-type.md)
- [Create a webhook delivery replay job](https://docs.cope.com/api-reference/create-a-webhook-delivery-replay-job.md)
- [Retrieve a webhook delivery replay job](https://docs.cope.com/api-reference/retrieve-a-webhook-delivery-replay-job.md)
- [Checkout SDK overview](https://docs.cope.com/checkout-sdk/overview.md): Use the COPE Checkout SDK to build custom product and cart pages that hand buyers off to hosted checkout by redirect or iframe.
- [Embedded hosted checkout](https://docs.cope.com/checkout-sdk/embedded-checkout.md): Mount COPE hosted checkout in an iframe with the Checkout SDK, registered embed origins, and trusted postMessage events.
- [Prefilled checkout](https://docs.cope.com/checkout-sdk/prefilled-checkout.md): Create a cart, its lines, the buyer identity and a hosted checkout session in one Checkout SDK call with createPrefilledCheckout().
- [Checkout from your server](https://docs.cope.com/checkout-sdk/server-checkout.md): Create a checkout with your secret API key, with the product, plan, buyer email and your reference fixed, and confirm the order by the checkout's id.
- [MCP for AI shopping agents (cope-sdk/mcp)](https://docs.cope.com/ai-agents/shopping-agents.md): Mount an MCP endpoint on your own server so a buyer's AI agent can build a cart in your store and hand the buyer a COPE checkout link.
- [MCP server for your store (cope-mcp)](https://docs.cope.com/ai-agents/merchant-assistant.md): Let Claude, Cursor or another MCP client read your COPE store: orders, payments, refunds, invoices, products, offers, subscriptions and webhook deliveries.
- [Changelog](https://docs.cope.com/changelog.md): New features, improvements and fixes for developers building on COPE, week by week.
- [Webhooks overview](https://docs.cope.com/webhooks/overview.md): COPE delivers public webhook events as signed JSON with at-least-once delivery.
- [Webhook endpoints](https://docs.cope.com/webhooks/endpoints.md): Manage where COPE sends webhook events and how endpoint secrets are handled.
- [Webhook deliveries and replay](https://docs.cope.com/webhooks/deliveries.md): Inspect webhook delivery attempts, replay failed deliveries, and send test events.
- [Event type discovery](https://docs.cope.com/webhooks/event-types.md): Discover COPE webhook event types and their payload schema availability.
- [Webhook signing](https://docs.cope.com/webhooks/signing.md): Verify COPE webhook signatures before processing events.
- [Who started a refund](https://docs.cope.com/webhooks/refund-initiator.md): What initiated_via on refund events means, and when it is absent.
- [Webhook events](https://docs.cope.com/webhooks/events/index.md): Public COPE webhook events and payload schema availability.
- [cart.product.created](https://docs.cope.com/webhooks/events/cart.product.created.md): A product has been created.
- [cart.product.approval_status.changed](https://docs.cope.com/webhooks/events/cart.product.approval_status.changed.md): A product's approval status has changed.
- [cart.cart.created](https://docs.cope.com/webhooks/events/cart.cart.created.md): A cart has been created.
- [cart.cart_line.added](https://docs.cope.com/webhooks/events/cart.cart_line.added.md): A line item has been added to a cart.
- [cart.cart_line.removed](https://docs.cope.com/webhooks/events/cart.cart_line.removed.md): A line item has been removed from a cart.
- [cart.cart.abandoned](https://docs.cope.com/webhooks/events/cart.cart.abandoned.md): A cart has been abandoned.
- [cart.checkout.created](https://docs.cope.com/webhooks/events/cart.checkout.created.md): A checkout has been created.
- [cart.checkout.cancelled](https://docs.cope.com/webhooks/events/cart.checkout.cancelled.md): A checkout has been cancelled.
- [cart.checkout.expired](https://docs.cope.com/webhooks/events/cart.checkout.expired.md): A checkout has expired.
- [cart.order.created](https://docs.cope.com/webhooks/events/cart.order.created.md): An order has been created.
- [cart.order.completed](https://docs.cope.com/webhooks/events/cart.order.completed.md): An order has completed successfully.
- [cart.order.failed](https://docs.cope.com/webhooks/events/cart.order.failed.md): An order has failed.
- [payment.sale.succeeded](https://docs.cope.com/webhooks/events/payment.sale.succeeded.md): A payment sale has succeeded.
- [payment.failed](https://docs.cope.com/webhooks/events/payment.failed.md): A payment sale has failed.
- [payment.attempt.failed](https://docs.cope.com/webhooks/events/payment.attempt.failed.md): An attempt to charge a payment was declined.
- [payment.refund.created](https://docs.cope.com/webhooks/events/payment.refund.created.md): A refund has been created.
- [payment.refund.reversed](https://docs.cope.com/webhooks/events/payment.refund.reversed.md): A previously created refund has been reversed.
- [subscription.amount_changed](https://docs.cope.com/webhooks/events/subscription.amount_changed.md): The recurring amount on a live subscription has changed.
- [subscription.plan_changed](https://docs.cope.com/webhooks/events/subscription.plan_changed.md): A live subscription has been moved onto a different payment plan.
- [subscription.paused](https://docs.cope.com/webhooks/events/subscription.paused.md): A subscription has stopped collecting renewals.
- [subscription.resumed](https://docs.cope.com/webhooks/events/subscription.resumed.md): A subscription you paused is collecting renewals again.
- [subscription.cancelled](https://docs.cope.com/webhooks/events/subscription.cancelled.md): A subscription has been cancelled, and `cancellation_reason` says why.
- [payment.dispute.opened](https://docs.cope.com/webhooks/events/payment.dispute.opened.md): A payment dispute has opened.
- [payment.dispute.won](https://docs.cope.com/webhooks/events/payment.dispute.won.md): A payment dispute has been won.
- [payment.dispute.lost](https://docs.cope.com/webhooks/events/payment.dispute.lost.md): A payment dispute has been lost.
- [payment.dispute.counter_fee.created](https://docs.cope.com/webhooks/events/payment.dispute.counter_fee.created.md): A dispute counter fee has been created.
- [payment.chargeback.created](https://docs.cope.com/webhooks/events/payment.chargeback.created.md): A chargeback has been created.
- [payment.chargeback.reversed](https://docs.cope.com/webhooks/events/payment.chargeback.reversed.md): A chargeback has been reversed.
- [payouts.transfer.initiated](https://docs.cope.com/webhooks/events/payouts.transfer.initiated.md): A payout transfer has been initiated.
- [payouts.transfer.completed](https://docs.cope.com/webhooks/events/payouts.transfer.completed.md): A payout transfer has completed.
- [payouts.external_payout.paid](https://docs.cope.com/webhooks/events/payouts.external_payout.paid.md): A payout has reached the bank.
- [payouts.external_payout.failed](https://docs.cope.com/webhooks/events/payouts.external_payout.failed.md): A payout to the bank has failed.
- [payouts.external_payout.canceled](https://docs.cope.com/webhooks/events/payouts.external_payout.canceled.md): A payout to the bank was canceled.
- [Cart, checkout, and order lifecycle](https://docs.cope.com/reference/cart-checkout-order-lifecycle.md): Cart, checkout, and order states and the webhook events that announce lifecycle transitions.
- [Payment lifecycle](https://docs.cope.com/reference/payment-lifecycle.md): Public payment states and the webhook events that announce terminal payment, refund, and dispute transitions.
- [Event envelope](https://docs.cope.com/reference/event-envelope.md): The fields every COPE webhook delivery carries around its event body.

## OpenAPI Specs

- [account-platform-webhooks-v1.openapi](/api-reference/account-platform-webhooks-v1.openapi.json)
- [commerce-v1.openapi](/api-reference/commerce-v1.openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.