Commerce API resources

Ownership and pagination

Core commerce reads require Sanctum authentication and the matching token ability. Lists are scoped to authenticated_customer(), sorted by descending ID, and paginated at 20 rows. Detail routes also enforce ownership and return 404 for another customer's object. Supplying customer_id does not change the authenticated customer.

Core lists use Laravel resource pagination: data is an array with links and meta. A detail response has one object under data. Use ?page=2 for the next page; the controllers do not accept an arbitrary page size. Read-only operations have no JSON request body.

curl 'https://shop.example.test/api/v1/orders?page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

curl "https://shop.example.test/api/v1/invoices/$INVOICE_ID" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

curl 'https://shop.example.test/api/v1/credit-notes?page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

curl "https://shop.example.test/api/v1/support-tickets/$TICKET_ID" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

Source: CommerceController. The complete endpoint map lists each collection and detail path.

Shared field shapes

The following shapes are documentation shorthand, not separately exposed endpoints:

Amounts are minor-unit integers associated with the document's currency. Formatted fields are display strings and can be localized. Financial responses expose both custom_properties and custom_properties_snapshot, each populated from the stored snapshot or []. Do not use those responses to infer the current editable customer-property schema.

Status values

Status strings come from distinct enums. Do not apply a payment status to an order or invoice:

These are serialized states, not a promise that a client can request every transition. Sources: OrderStatus, PaymentStatus, InvoiceStatus, CreditNoteStatus, TicketStatus, and TicketPriority.

Order resource

GET /orders and GET /orders/{order} require orders.read. The checkout action returns the same resource type.

The payment summary contains status, amount, amount_formatted, refunded_amount, and net_amount. It does not expose the gateway credentials or a provider's full payment object. invoice is a convenience summary of the first loaded invoice; use invoices to handle multiple documents. A credit note and a cash refund are distinct records.

Source: OrderResource. Order responses intentionally omit the private storefront access token; StorefrontApiTest checks this and cross-customer access.

Invoice and credit-note resources

GET /invoices and GET /invoices/{invoice} require invoices.read. Invoice fields are:

• id, number, status, nullable date-only issued_at, and currency.
• customer, billing, custom_properties, and custom_properties_snapshot.
• Integer subtotal_amount, tax_amount, total_amount, and credited_amount, plus total_formatted.
• Nullable order containing id, number, and status.
• items and credit_notes arrays using the shapes above.

GET /credit-notes and GET /credit-notes/{creditNote} require credit_notes.read. Credit-note fields are:

• id, number, status, reason, date-only issued_at, invoice_id, and currency.
• customer, billing, custom_properties, and custom_properties_snapshot.
• Integer subtotal_amount, tax_amount, and total_amount, plus total_formatted.
• items containing line-item summaries.

These JSON endpoints are not PDF downloads. Neither resource includes a public mutation method or arbitrary document HTML. Read the InvoiceResource and CreditNoteResource before adding client-side assumptions about optional fields.

Support tickets

GET /support-tickets and GET /support-tickets/{ticket} require tickets.read. Both serialize id, number, subject, status, priority, nullable ISO 8601 last_reply_at, and nullable ISO 8601 created_at.

The detail endpoint is still a summary. It does not return message bodies, attachments, staff notes, or a reply form. There are no Core v1 write routes for opening or replying to support tickets. Source: SupportTicketResource.

Optional Module endpoints

These routes are registered by enabled Modules through ModuleContext::apiRoutes(). They are not permanently present in Core. They use api, auth:sanctum, throttle:api, and ability middleware. The download file route adds throttle:api-sensitive.

Module lists return data and a compact meta object with current_page, last_page, and total. They paginate at 20 rows, newest ID first, and do not add Core's full pagination links. All are customer-scoped. There is no public v1 service action, subscription cancellation, ticket check-in, or digital-secret pool-management route in these registration blocks.

Subscriptions and provisioned services

A subscription contains id, number, status, nullable product name product, interval, integer interval_count, integer price_amount, currency, nullable ISO 8601 current_period_end and next_billing_at, and boolean cancel_at_period_end.

A service contains id, number, status, nullable product name product, external_ref, nullable ISO 8601 activated_at, and nullable ISO 8601 suspended_at. It does not expose provider administration credentials.

Sources: SubscriptionApiController and ServiceApiController.

Files and digital secrets

A download list row contains token, nullable label and filename, download_count, download_limit, boolean can_download, and ISO 8601 granted_at. The list excludes revoked entitlements. GET /downloads/{token} returns a streamed file, not JSON, after ownership and delivery checks. An unavailable download can return 409 invalid_state.

curl "https://shop.example.test/api/v1/downloads/$DOWNLOAD_TOKEN" \
  --header "Authorization: Bearer $AGOVENA_TOKEN" \
  --fail --output purchased-file.bin

Store the token privately and check the response status before treating the output as a file.

A digital-secret row contains id, nullable product name product, status, value_hint, value, and nullable ISO 8601 granted_at. value can contain plaintext delivered content. It is returned only when the row is readable by the owning customer; otherwise it is null. Do not send these responses to analytics, shared caches, or general request logs. This is not the merchant's available secret pool.

Sources: DownloadApiController and SecretApiController.

Event tickets

An event ticket contains number, token, status, nullable event, venue, starts_at, ticket_type, and checked_in_at. Timestamps use ISO 8601. Venue prefers the performance venue, then the event venue. The list excludes void tickets; the detail action does not apply the same status filter. Detail lookup uses the ticket token, not its numeric ID.

curl 'https://shop.example.test/api/v1/event-tickets?page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

Source: EventTicketController. See ModuleContext for shared route middleware and ApiTokenAbilities for route-name-to-ability mapping.