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/

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

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	yes	string	yyyy-mm-dd

{
    "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', '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": "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

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
reason	Set a reason why you cancel or revoke the access to the user	no	string

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
201	Object Created
422	Validation error, the reason of the error will be described in the response body
401	Unauthenticated

Base URL​

Endpoints​

Headers​

info

Create​

Automatic creation of missing resources:​

Completing the checkout for sale orders​

Body Request​

Response​

Get​

tip

Parameters​

Query Params​

Response​

Update​

Parameters​

Query params​

Body request​

Response​

Cancel​

Parameters​

Query params​

Body request​

Response​

Base URL

Endpoints

Headers

Create

Automatic creation of missing resources:

Completing the checkout for `sale` orders

Body Request

Response

Get

Parameters

Query Params

Response

Update

Parameters

Query params

Body request

Response

Cancel

Parameters

Query params

Body request

Response