Products API

Use the Products API to manage the Products

Create a Product

POST /v1/organizations/{{id}}/ledgers/{{id}}/products

Use this endpoint to create a Product.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
  "name": "Standard",
  "status": { //optional, default status.code = ACTIVE and status.description = null 
    "code": "001",
    "description": "Ready to use"
  },
  "metadata": {
    "internalProductId": 21
  }
}

Response codes

201

{
  "id": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
  "ledgerId": "44d5e310-5caa-4d51-812f-2d56c1bbcacd",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "name": "Standard",
  "status": { null
    "code": "001",
    "description": "Ready to use"
  },
  "metadata": {
    "internalProductId": 21
  },
  "createdAt": "2024-01-29T00:12:00+0300",
  "updatedAt": "2024-01-29T00:12:00+0300",
  "deletedAt": null
}

400

{
   "code":"0015",
   "title":"Duplicate Product Name Error",
   "message":"A product with the name {{name}} already exists for this ledger ID {{ledgerId}}. Please try again with a different ledger or name."
}

---

Retrieve all Products

GET /v1/organizations/{{id}}/ledgers/{{id}}/products

Use this endpoint to retrieve the information of all Products to which a user has access.

If a product has been deleted, the information of the product will be displayed, including the date when the deletion occurred in the deletedAt field.

Headers

Name	Value
Authorization	Bearer <token>

Query parameters

Name	Type	Description
status	Array	An object containing information about the product status.
ledgerId	String (UUID)	Ledger's identification code.

Response codes

200

[
  {
    "id": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
    "ledgerId": "44d5e310-5caa-4d51-812f-2d56c1bbcacd",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "Standard",
    "status": {
      "code": "001",
      "description": "Ready to use"
    },
    "metadata": {
      "internalProductId": 21
    },
    "createdAt": "2024-01-29T00:12:00+0300",
    "updatedAt": "2024-01-29T00:12:00+0300",
    "deletedAt": null
  },
  {
    "id": "9099ce3f-32bd-482f-9617-16c7809681aa",
    "name": "Vip clients",
    "ledgerId": "44d5e310-5caa-4d51-812f-2d56c1bbcacd",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "status": {
      "code": "INACTIVE",
      "description": "Deleted by @gabriel"
    },
    "metadata": {
      "internalProductId": 99,
      "price": 449.99
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
  }
]

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}

---

Retrieve Product by id

GET /v1/organizations/{{id}}/ledgers/{{id}}/products/{{id}}

Use this endpoint to retrieve the information of a specific Product using the identifier (id).

If the product has been deleted, the information of the product will be displayed, including the date when the deletion occurred in the deletedAt field.

Headers

Name	Value
Authorization	Bearer <token>

Response codes

200

{
  "id": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
  "name": "Standard",
  "ledgerId": "44d5e310-5caa-4d51-812f-2d56c1bbcacd",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "status": {
    "code": "001",
    "description": "Ready to use"
  },
  "metadata": {
    "internalProductId": 21
  },
  "createdAt": "2024-01-29T00:12:00+0300",
  "updatedAt": "2024-01-29T00:12:00+0300",
  "deletedAt": null
}

200 - Deleted

{
   "id":"9099ce3f-32bd-482f-9617-16c7809681aa",
   "name":"Vip clients",
   "ledgerId":"44d5e310-5caa-4d51-812f-2d56c1bbcacd",
   "organizationId":"5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
   "status":{
      "code":"INACTIVE",
      "description":"Deleted by admin"
   },
   "metadata":{
      "internalProductId":99,
      "price":449.99
   },
   "createdAt":"2024-02-08T16:59:31+0300",
   "updatedAt":"2024-02-08T16:59:31+0300",
   "deletedAt":"2024-03-18T15:04:57+0300"
}

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}

---

Update a Product

PATCH /v1/organizations/{{id}}/ledgers/{{id}}/products/{{id}}

Use this endpoint to edit and update the information of a specific Product. When you update a Product, the following fields can be edited:

• name

• status

• metadata

When updating the metadata object, all previous key-value pairs must be included in the update, or they will be removed.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
  "name": "Basic",
  "status": {
      "code": "002",
      "description": "Blocked"
  },
  "metadata": {
    "countryCode": "BR"
  }
}

Response codes

200

{
  "id": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
  "name": "Basic",
  "ledgerId": "44d5e310-5caa-4d51-812f-2d56c1bbcacd",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "status": {
    "code": "002",
    "description": "Blocked"
  },
  "metadata": {
    "countryCode": "BR"
  },
  "createdAt": "2024-01-29T00:12:00+0300",
  "updatedAt": "2024-01-29T00:12:00+0300",
  "deletedAt": null
}

400

{
   "code":"0006",
   "title":"Unmodifiable Field Error",
   "message":"Your request includes a field that cannot be modified. Please review your request and try again, removing any uneditable fields. Please refer to the documentation for guidance."
}

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}

---

Delete a Product

DELETE /v1/organizations/{{id}}/ledgers/{{id}}/products/{{id}}

Use this endpoint to deactivate a specific Product.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Response codes

204

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}