Orders API Overview

What is the Orders API?

The Orders API enables you to manage customer purchases and access permissions for products on your Publica.la platform. It supports creating, retrieving, updating, and canceling orders programmatically.

Authentication Required

Make sure you have generated an API token in your store dashboard. See the API Authentication guide for details.

Available Order Types

The Orders API supports three distinct order types, each designed for specific integration scenarios:

Order Type	Use Case	Payment Record	Initial Status	Best For
Permission	Grant content access	No payment record created	approved	Own e-commerce integrations, legacy permissions migration
Report	Assign content + record payment	Payment record created in Publica.la	approved	Own e-commerce integrations, External Marketplace sales
Sale	Publica.la checkout flow	Payment processed via gateway	pending	Direct sales through Publica.la initiated from outside

Choosing the Right Order Type

Use Permission Orders when:

• You process payments in your own e-commerce

  • You collect payment in your system
  • You want to use Publica.la only for content delivery
  • No financial record needed in Publica.la

• Want to migrate legacy from a previous system to Publica.la or grant free access

  • Migrating legacy access from previous implementations
  • Manual content assignments

Use Report Orders when:

• Recording sales with financial tracking

  • Need to track sales in Publica.la's financial system
  • Creating payment records for accounting/reporting
  • Can also be used for your own content if you need financial tracking

• Granting access to Publica.la's marketplace content

  • You collected payment in your system but want to grant access to marketplace content (requires support enablement)

Marketplace Content

Report orders are primarily used for marketplace content (content you don't own). Contact support to enable marketplace content sales. You can also use Report for your own content if you need financial records in Publica.la.

Use Sale Orders when:

• Using Publica.la's checkout system
  • Customer pays directly through Publica.la
  • Payment processed via Stripe or MercadoPago
  • Full payment gateway integration needed
  • Automatic payment status updates

Example scenarios:

• "Your own e-commerce site with 'Buy Now' button redirecting to Publica.la"
• "You don't want to handle payments"

Common API Operations

Core Endpoints

Operation	Endpoint	Supported Types
Create order	POST /integration-api/v1/orders	All types
List orders	GET /integration-api/v1/orders	All types
Get specific order	GET /integration-api/v1/orders/{id}	All types
Update order	PUT /integration-api/v1/orders/{id}	All types
Cancel order	DELETE /integration-api/v1/orders/{id}	All types

Order Identification

Orders can be identified using either:

• Internal ID: Publica.la's UUID (e.g., ?id_type=internal)
• External Reference: Your system's ID (e.g., ?id_type=external)

Order Lifecycle

Permission Order:  [Create] → approved ✓
Report Order:      [Create] → approved ✓
Sale Order:        [Create] → pending → [User Pays] → approved ✓

All order types support these status transitions:

• approved → paused or cancelled
• paused → approved or cancelled
• cancelled is final (no further changes)

Resource Auto-Creation

The Orders API automatically creates resources when they don't exist:

Users

If a user.id doesn't exist, a new user is created with:

• The provided user.id (your system's external ID)
• The provided user.email

Products (Sale orders only)

For sale type orders, if a product doesn't exist and you provide:

• products.*.name
• products.*.url

A new product of type 'link' will be created automatically.

Next Steps

Choose the order type that fits your integration:

• Permission Orders - Grant access without payment records
• Report Orders - Assign content + create payment records
• Sale Orders - Publica.la checkout with payment processing

Common Response Format

All order types return responses with these common fields:

Field	Type	Description
id	string	Publica.la's unique order ID (UUID)
external_reference	string	Your unique ID for this order
type	string	Order type: permission, report, or sale
status	string	Order status: approved, pending, paused, or cancelled
user	object	User information
products	array	Products included in the order
created_at	string	Creation timestamp

See individual order type documentation for complete field reference.