Skip to main content

Orders API Reference

Overview​

The Orders API facilitates the management of customer purchases and access permissions for products on your platform. It supports creating, retrieving, updating, and canceling orders, with different types of orders available to suit various business needs.

info

Make sure you generated the api_token on your store. More info in the API Authentication guide

Order Types Overview​

There are three types of orders you can create via the API:

Order TypeDescriptionPaymentStatus
PermissionGrant access to a product or plan without generating a sales recordNo payment gateway involvedImmediately approved
ReportRecord an external transaction (e.g., POS sale) in Publica.laBypasses payment gateway (payment assumed complete)Immediately approved
SaleInitiate a standard checkout process through an integrated payment gatewayPayment required through gatewayStarts as pending, transitions to approved upon payment

Endpoint Reference​

EndpointMethodDescription
/integration-api/v1/ordersPOSTCreate a new order
/integration-api/v1/ordersGETList or search for orders
/integration-api/v1/orders/(id_or_external_ref)GETRetrieve a specific order
/integration-api/v1/orders/(id_or_external_ref)PUTUpdate an existing order
/integration-api/v1/orders/(id_or_external_ref)DELETECancel an order

Create an Order​

Create a new order of type permission, report, or sale.

Endpoint: POST /integration-api/v1/orders

Automatic Resource Creation​

  • Users: If the user.id provided doesn't exist, a new user will be created automatically using the provided user.id and user.email
  • Products: For sale orders, if a product doesn't exist, it will be created automatically if products.*.name and products.*.url are provided

Common Request Body Fields​

FieldTypeDescriptionRequired
typestringOrder type: permission, report, or saleYes
external_referencestringYour unique identifier for this order (max 64 chars)No
userobjectUser informationYes
user.idstringUser unique ID in your system (max 64 chars)Yes
user.emailstringUser's email addressYes
productsarrayArray of products included in the orderYes
products.*.typestringProduct type: content or subscriptionYes
products.*.idstringProduct unique ID in your system (max 64 chars)Yes
products.*.expiration_datestringOptional: Date when user access expires (YYYY-MM-DD)No

Type-Specific Request Fields​

Additional fields for Permission orders:

FieldTypeDescriptionRequired
unit_pricefloatNot typically used, but can be setNo
currency_idstringNot typically used, but can be set (ISO 4217 code)No
products.*.namestringProduct name (not required for permission orders)No
products.*.urlstringProduct URL (not required for permission orders)No
products.*.unit_pricefloatProduct price (not typically used)No
products.*.currency_idstringProduct currency (not typically used)No

Example Request (Permission)​

{
  "type": "permission",
  "external_reference": "GRANT-ACCESS-001",
  "user": {
    "id": "user-ext-123",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "SUB-MONTHLY",
      "type": "subscription"
    },
    {
      "id": "BOOK-XYZ",
      "type": "content",
      "expiration_date": "2024-12-31"
    }
  ]
}

Response (Create)​

A successful creation returns 201 Created with the following fields:

FieldTypeDescription
idstringPublica.la's unique order ID (UUID)
external_referencestringYour unique ID, if provided in the request
typestringThe order type (permission, report, sale)
unit_pricefloatOrder price
currency_idstringOrder currency
statusstringOrder status (approved, pending)
created_atstringCreation date (YYYY-MM-DD)
userobjectUser information
productsarrayArray of products with status and details
checkoutobjectFor sale orders with pending status only: URL and expiration for payment

Example Response (Permission - Approved)​

{
  "data": {
    "id": "03033649-de10-404b-aa8a-8682871001c2",
    "external_reference": "GRANT-ACCESS-001",
    "type": "permission",
    "unit_price": 0,
    "currency_id": null,
    "status": "approved",
    "created_at": "2024-07-29",
    "user": {
      "id": "user-ext-123",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "SUB-MONTHLY",
        "type": "subscription",
        "name": "Monthly Subscription",
        "status": "approved",
        "expiration_date": null,
        "cover": "https://cdn.publica.la/plan/cover.jpg",
        "reader_url": null,
        "description": null,
        "pages_quantity": null,
        "file_type": null,
        "is_free": false,
        "unit_price": 0
      },
      {
        "id": "BOOK-XYZ",
        "type": "content",
        "name": "The Great Book",
        "status": "approved",
        "expiration_date": "2024-12-31",
        "cover": "https://cdn.publica.la/item/12345.jpg",
        "reader_url": "https://{store_final_domain}/reader/the-great-book",
        "description": "An amazing story.",
        "pages_quantity": 300,
        "file_type": "epub",
        "is_free": false,
        "unit_price": 0
      }
    ]
  }
}

Example Response (Sale - Pending)​

{
  "data": {
    "id": "a4b5c6d7-e8f9-4a0b-bc1d-e2f3a4b5c6d7",
    "external_reference": "WEB-ORDER-789",
    "checkout": {
        "url": "https://{store_final_domain}/auth/token?external-auth-token={AUTH-TOKEN}",
        "expires_on" : "2024-07-29 14:30:00"
    },
    "type": "sale",
    "unit_price": 15.50,
    "currency_id": "ARS",
    "status": "pending",
    "created_at": "2024-07-29",
    "user": {
      "id": "user-ext-789",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "product-ext-003",
        "type": "content",
        "name": "Online Course Access",
        "status": "pending",
        "cover": "https://example.publica.la/images/cover-image-03.png",
        "reader_url": "https://{store_final_domain}/reader/online-course-access",
        "description": "Access to the online course.",
        "pages_quantity": null,
        "file_type": "external_link",
        "is_free": false,
        "unit_price": 15.50,
        "currency_id": "ARS"
      }
    ]
  }
}

Response Codes​

CodeDescription
201Order created successfully
422Validation error (details in response)
401Unauthorized (invalid API token)

Get Orders​

Retrieve one or more orders.

Endpoints:

  • GET /integration-api/v1/orders (list all orders, paginated)
  • GET /integration-api/v1/orders/(id_or_external_ref) (get specific order)

Query Parameters​

ParameterTypeDescriptionRequiredExample
id_typestringWhen getting specific order: internal or externalYes?id_type=internal
user_idstringFilter by user IDNo?user_id=user-ext-123
user_emailstringFilter by user emailNo[email protected]
product_idstringFilter by product IDNo?product_id=product-123
product_typestringRequired if product_id is usedConditional?product_type=content
start_atstringFilter by creation date, from (YYYY-MM-DD)No?start_at=2024-01-01
end_atstringFilter by creation date, to (YYYY-MM-DD)No?end_at=2024-07-31

Example Requests​

  • Get by internal ID: GET /integration-api/v1/orders/03033649-de10-404b-aa8a-8682871001c2?id_type=internal
  • Get by external reference: GET /integration-api/v1/orders/WEB-ORDER-789?id_type=external
  • List by product: GET /integration-api/v1/orders?product_id=product-ext-003&product_type=content
  • List by date range: GET /integration-api/v1/orders?start_at=2024-07-01&end_at=2024-07-31

Response​

The response format is the same as the Create response, with pagination metadata when listing multiple orders.

Example Response (List Orders)​

{
  "data": [
    {
      "id": "c9f2b7b0-dc74-4c58-92a7-9dfcf93aed38",
      "external_reference": "123-abc",
      "unit_price": 17,
      "currency_id": "USD",
      // ... other fields ...
    },
    {
      "id": "a4b5c6d7-e8f9-4a0b-bc1d-e2f3a4b5c6d7",
      "external_reference": "WEB-ORDER-789",
      // ... other fields ...
    }
  ],
  "links": {
    "first": "https://{store_final_domain}/integration-api/v1/orders?page=1",
    "last": "https://{store_final_domain}/integration-api/v1/orders?page=5",
    "prev": null,
    "next": "https://{store_final_domain}/integration-api/v1/orders?page=2"
   },
   "meta": {
     "current_page": 1,
     "from": 1,
     "last_page": 5,
     "path": "https://{store_final_domain}/integration-api/v1/orders",
     "per_page": 15,
     "to": 15,
     "total": 70
   }
}

Response Codes​

CodeDescription
200Success
404Order not found
401Unauthorized (invalid API token)

Update an Order​

Update an existing order's status or expiration date.

Endpoint: PUT /integration-api/v1/orders/(id_or_external_ref)

Status Transitions

Only the following status transitions are allowed:

  • approved → paused or cancelled
  • paused → approved or cancelled
  • cancelled is a final status that cannot be changed

Path Parameters​

ParameterTypeDescriptionRequired
id_or_external_refstringInternal ID or external referenceYes

Query Parameters​

ParameterTypeDescriptionRequired
id_typestringinternal or externalYes
product_idstringSpecific product ID to update (optional)No
product_typestringRequired if product_id is usedConditional

Request Body​

FieldTypeDescriptionRequired
statusstringNew status (approved, paused, cancelled)Conditional
expiration_datestringNew expiration date (YYYY-MM-DD) or null to removeConditional
note

At least one of status or expiration_date must be provided.

Example Request​

{
  "expiration_date": "2025-12-31",
  "status": "paused"
}

Response​

A successful update returns 200 OK with the updated order details in the same format as the Create response.

Response Codes​

CodeDescription
200Order updated successfully
422Validation error (details in response)
404Order not found
401Unauthorized (invalid API token)

Cancel an Order​

Cancel an order, revoking access to the associated products.

Endpoint: DELETE /integration-api/v1/orders/(id_or_external_ref)

warning

Cancellation is irreversible. Once an order is cancelled, it cannot be reactivated.

Path Parameters​

ParameterTypeDescriptionRequired
id_or_external_refstringInternal ID or external referenceYes

Query Parameters​

ParameterTypeDescriptionRequired
id_typestringinternal or externalYes

Request Body (Optional)​

FieldTypeDescriptionRequired
reasonstringReason for cancellation (max 150 chars)No
expiration_datestringFuture date for cancellation (YYYY-MM-DD)No

Response​

A successful cancellation returns 200 OK with:

FieldTypeDescription
idstringPublica.la's internal order ID
external_referencestringYour external reference ID

Example Response​

{
  "data": {
    "id": "03033649-de10-404b-aa8a-8682871001c2",
    "external_reference": "123-abc"
  }
}

Response Codes​

CodeDescription
200Order cancelled successfully
422Validation error (details in response)
404Order not found
401Unauthorized (invalid API token)

Common Error Scenarios​

ErrorDescriptionSolution
Invalid user IDUser ID doesn't exist or can't be createdCheck user ID format and data
Invalid product IDProduct ID doesn't exist or can't be createdEnsure product details are complete if auto-creation is needed
Invalid status transitionAttempting disallowed status changeOnly use allowed status transitions
Order not foundThe specified order doesn't existVerify ID and id_type parameter
Expired checkoutCheckout URL has expiredGet a fresh checkout URL using the GET endpoint
X

Graph View