Orders

Order objects are created to handle end customers' purchases of already existing products. You can create, retrieve and update individual orders, as well as list all orders. Orders are identified by a unique autogenerated ID as well as an external ID set by yourself.

Base URL

All following endpoints operates over the URL of your store: https://your-store.com/

example: https://alephdigital.publica.la/

Endpoints

• Create
• Get
• Update
• Cancel

Headers

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "X-User-Token": api_token,
}

info

Make sure you generated the api_token on your store. More info HERE

Create

POST /integration-api/v1/orders

example: https://your-store.com/integration-api/v1/orders

First of all, there are two types of orders.

• Permission orders: Used to assign a publication or plan to a user. This would grant access, but it won't count as a transaction in the sales report
• Sale orders: Used to generate a checkout session in a gateway. The order will remain in the 'pending' status until the user completes its payment in the gateway. If the payment is a success, the order then transitions to the 'approved' status. This order also grants access to a publication or plan, but it will be reported as a transaction in the sales report

Automatic creation of missing resources:

When creating both sale and permission orders, if the user doesn't exist, it's created automatically. That's why the user.id is required.

When creating sale orders only, if the product doesn't exist, it's created automatically. For this to happen, we need the product fields name and url, in addition to the fields already "required for sale".
The newly created product will be type "External link" and it will be pointing to that url. It will only be accessible through the API or the store dashboard, it won't be displayed in the storefront.

Completing the checkout for sale orders

When creating a sale order, the response will include a checkout.token property containing an external-auth-token url and checkout.ttl with its ttl in seconds. You should redirect your user to that URL, and we'll automatically authenticate them and redirect them to the corresponding gateway checkout. After they complete the payment, they will be redirected to the return_url you set for your order.
We will add a query string to that return_url containing the following payment data:

• order-id: The order ID in our system
• order-external-id: The order ID in your system
• status: the resulting status after the payment (approved, pending, cancelled)

Keep in mind that a checkout.token expires after checkout.ttl seconds, you can always generate a new one manually or by retrieving the order using the GET endpoint

Body Request

Field	Description	Required for permission	Required for sale	Type	Format
type	Order type	yes	yes	string	permission or sale
external_reference	Order unique ID in your system	no	no	string	max 64
return_url	An url to return to, after finishing the checkout	no	yes	string	url
unit_price	Order price	no	yes	float
currency_id	Order currency	no	yes	string	ISO 4217. All supported for permission. Only ARS supported for sale
user	User object	yes	yes	object
user.id	User unique ID in your system	Required if user.email is null	yes	string	max 64
user.email	User Email	Required if user.id is null	no	string	email
products	List of products	yes	yes	objects array
products.*.type	Product type	yes	yes	string	content or subscription
products.*.id	Product unique ID in your system	yes	yes	string	max 64
products.*.name	Product name	no	yes*	string	max 64. (*) It's required only when using the automatic creation of products
products.*.url	Product url	no	yes*	string	url. (*) It's required only when using the automatic creation of products
products.*.unit_price	Product price	no	yes	float	ISO 4217. All supported for permission. Only ARS supported for sale
products.*.currency_id	Product currency	no	yes	string
products.*.expiration_date	User will lose access to the content at this date	no	no	string	yyyy-mm-dd

JSON example for permission order:

{
 "external_reference": "123-abc",
 "user":{
  "id": "123",
  "email": "[email protected]"
 },
 "products": [{
  "id": "123",
  "type": "content",
  "expiration_date": "2023-12-31"
 }]
}

JSON example for sale order:

{
     "external_reference": "123-abc",
     "type": "sale",
     "unit_price": 10,
     "currency_id": "ARS",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "products": [{
        "id": "123",
        "type": "content",
        "unit_price": 10,
        "currency_id": "ARS"
     }]
 }

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string
source	Order creation source	string	internal or api
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
status		string
created_at	Date when the order was created.	string	yyyy-mm-dd
user		object
user.id	User unique ID in your system	string	max 64
user.email	User email	string	email
products	List of products	objects array
products.*.id	Product unique ID in your system	string
products.*.type		string	content or subscription
products.*.name		string
products.*.status		string
products.*.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.*.cover		string
products.*.reader_url		string
products.*.unit_price		float

JSON example for permission:

{  
  "data":
   {
     "id" : "03033649-de10-404b-aa8a-8682871001c2",
     "external_reference": "123-abc",
     "source": "api",
     "unit_price": 12.9,
     "currency_id": "USD",
     "status": "approved",
     "created_at": "2021-08-01",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "products": [{
          "id": "abc-123",
          "type": "content",
          "name": "abc product",
          "status": "approved",
          "expiration_date": "2021-12-31",
          "cover": "https://cdn.publica.la/item/3213123.jpg",
          "reader_url": "https://domain.com/reader/abc-product",
          "description": "abc product is...",
          "pages_quantity": 12,
          "file_type": "pdf",
          "is_free": false,
          "unit_price": 10
     }]
   }
}

JSON example for sale (when just created and still pending):

{  
  "data":
   {
     "id" : "03033649-de10-404b-aa8a-8682871001c2",
     "external_reference": "123-abc",
     "checkout": {
        "url": "https://your-store.com/auth/token?external-auth-token={AURH-TOKEN}",
        "expires_on" : "2023-01-01 12:00:00"
   },
     "source": "api",
     "unit_price": 10,
     "currency_id": "ARS",
     "status": "pending",
     "created_at": "2021-08-01",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "products": [{
          "id": "abc-123",
          "type": "content",
          "name": "abc product",
          "status": "pending",
          "cover": "https://cdn.publica.la/item/3213123.jpg",
          "reader_url": "https://domain.com/reader/abc-product",
          "description": "abc product is...",
          "pages_quantity": 12,
          "file_type": "pdf",
          "is_free": false
     }]
 }
}

Code	Description
200	Ok
201	Object Created
422	Validation error, the reason of the error will be described in the response body
401	Unauthenticated

JSON with errors example:

{
    "status": 422,
     "errors": [{
          "title": "Incorrect User ID",
          "details": ["Creation of the order failed due to incorrect user id"]
     }]
}

Get

Using this endpoint you can either paginate through all the orders, search for orders by different parameters, or get a specific order by ID

GET /integration-api/v1/orders/{id || external_reference}?id_type= &user_email= &product_id &product_type= &start_at= &end_at=

tip

Using query parameter you can filter by id_type, user_email, product_id, product_type, or by date range using start_at, end_at.

examples:

• Getting a specific order by the ID in our system:
  https://your-store.com/integration-api/v1/orders/some-id?id_type=internal
• Getting a specific order by the ID in your system:
  https://your-store.com/integration-api/v1/orders/some-other-id?id_type=external
• Searching for orders by product_id
  https://your-store.com/integration-api/v1/orders?product_id=some-product-id&product_type=content
• Searching for orders by date range
  https://your-store.com/integration-api/v1/orders?start_at=2022-01-01&end_at=2022-06-01
• Searching for orders by user email
  https://your-store.com/integration-api/v1/[email protected]
• Getting all your orders
  https://your-store.com/integration-api/v1/orders

Parameters

Field	Description	Type	Required	Format
id	Main or internal Order ID	string	no	max 64
external_reference	External reference or order ID	string	only if id_type=external	max 64

Query Params

Field	Description	Type	Required	Format
id_type	ID type	string	only when we set an ID or external_reference parameter	internal or external
user_id	User unique ID in your system	string	It is prioritized over user_email	max 64
user_email	User Email	string		email
product_type		string	only when we set a product_id	content or subscription
product_id	Product ID in your system	string		max 64
start_at	Date when the order was created	string		yyyy-mm-dd
end_at	Date when the order was created	string		yyyy-mm-dd

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string
checkout.token	When the order is pending, the url to continue the checkout	string
checkout.ttl	When the order is pending, the ttl in seconds	integer
source	Order creation source	string	internal or api
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
created_at	Date when the order was created.	string	yyyy-mm-dd
status	Status of the order	string	'approved', 'cancelled', 'pending'
user	Contains details of the user.	object
user.id	User unique ID in your system	string
user.email	User Email	string
products	Contains details of the product.	array object	Contains details of the products.
products.id	Product unique ID in your system	string
products.type		string	content or subscription
products.name		string
products.status		string
products.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.cover		string
products.reader_url		string
products.unit_price		float

JSON example:

{"data": [{
          "id": "c9f2b7b0-dc74-4c58-92a7-9dfcf93aed38",
          "external_reference": "123-abc",
          "unit_price": 17,
          "currency_id": "USD",
          "source": "api",
          "user": {
               "id": "123",
               "email": "[email protected]" 
          },
          "status": "approved",
          "created_at": "2022-01-18",
          "products": [
               {
                    "id": "978-987-805-082-9",
                    "type": "content",
                    "name": "Lorem Ipsum",
                    "cover": "https://storage/thumbnail.jpg",
                    "expiration_date": "2023-12-31",
                    "reader_url": "https://domain.com/reader/lorem-ipsum",
                    "description": "",
                    "pages_quantity": 324,
                    "file_type": "PDF",
                    "is_free": false,
                    "unit_price": 17,
                    "status": "approved"
               }
          ]
          }]
}

Update

PUT /integration-api/v1/orders/{id || external_reference}?id_type=

example: https://your-store.com/integration-api/v1/orders/123-abc?id_type=external

This endpoint can only update the expiration date of an order or a product and status

info

The paused status is applied instantly. You won't have the permissions granted by the order in question until you change its status to approved.

Parameters

Field	Description	Type	Required	Format
id	Main or internal Order ID	string	yes, when we don’t have an external_reference	max 64
external_reference	External reference or order ID	string	yes, when we don't have an id	max 64

Query params

Field	Required	Type	Format
id_type	yes, when using external_reference it should be external	string	internal or external
product_id	no	string	max 64
product_type	Conditional. Required if product_id is not null.	content or subscription

Body request

Field	Required	Type	Format
expiration_date	Conditional. Required if status is null.	string	yyyy-mm-dd
status	Conditional. Required if expiration_date is null.	string	approved or paused

{
    "expiration_date": "2023-12-31",
}

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string	string
source	Order creation source	string	internal or api
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
created_at	Date when the order was created.	string	yyyy-mm-dd
status	Status of the order	string	'approved', 'paused', 'pending'
user	Contains details of the user.	object
user.id	User unique ID in your system	string
user.email	User Email	string
products	Contains details of the product.	array object	Contains details of the products.
products.id	Product unique ID in your system	string
products.type		string	content or subscription
products.name		string
products.status		string
products.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.cover		string
products.reader_url		string
products.unit_price		float

JSON example:

{  
  "data": {
     "id": "03033649-de10-404b-aa8a-8682871001c2",
     "external_reference": "123-abc",
     "unit_price": 12.9,
     "currency_id": "USD",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "status": "approved",
     "created_at": "2020-04-13",
     "products": [
         {
          "id": "abc-123",
          "type": "content",
          "name": "abc product",
          "expiration_date": "2023-12-13",
          "cover": "https://cdn.publica.la/item/3213123.jpg",
          "reader_url": "https://domain.com/reader/abc-product",
          "description": "abc product is...",
          "pages_quantity": 12,
          "file_type": "PDF",
          "is_free": false,
          "unit_price": 10,
           "status": "approved"
        }
     ]
  }
}

Code	Description
200	Ok
201	Object Created
422	Validation error, the reason of the error will be described in the response body
401	Unauthenticated

JSON with errors example:

{
    "status": 422,
     "errors": [{
          "title": "Incorrect expiration date format",
          "details": ["Update failed due to incorrect expiration date format"],
     }]
}

Cancel

DELETE /integration-api/v1/orders/{id || external_reference}?id_type=

example: https://your-store.com/integration-api/v1/orders/123-abc?id_type=external

warning

Once deleted, the cancelled status cannot be reversed.

Parameters

Field	Description	Type	Required	Format
id	Main or internal Order ID	string	yes, when we don’t have an external_reference	max 64
external_reference	External reference or order ID	string	yes, when we don't have an id	max 64

Query params

Field	Required	Type	Format
id_type	yes, when using external_reference it should be external	string	internal or external

Body request

Field	Description	Required	Type	Format
reason	Set a reason why you cancel or revoke the access to the user.	no	string	max 150
expiration_date	User will lose access to the content at this date. If it is not specified and it is a subscription, it will be canceled once the current period has ended, otherwise the cancellation will be immediate.	no	string	yyyy-mm-dd

Response

Field	Description	Type
id	Main or internal order ID	string
external_reference	External reference or order ID	string

JSON example:

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

Code	Description
200	Ok
422	Validation error, the reason of the error will be described in the response body
401	Unauthenticated