API docs by Redocly

Nodeblocks Order Service Default Adapter API Specification (1.0)

Download OpenAPI specification:Download

Basal Inc.: marty@basal.dev URL: https://www.basal.dev/ Terms of Service

OrderService API spec (Default Adapter)

API documentation for OrderService default adapter.

App

Get app status

Retrieves app status information.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "packageInfo": {
    }
}

Order

Get all orders

Retrieves a list of orders across all users and organizations.

This operation requires user is

  • a system admin
Authorizations:
(bearerAuthx-nb-fingerprint)
query Parameters
$skip
integer
Example: $skip=100

The maximum number of the items to skip (The Default value is 0).

$nextToken
string
Example: $nextToken=token

A unique token to get next batch of data. (base64 format)

$previousToken
string
Example: $previousToken=token

A unique token to get previous batch of data. (base64 format)

$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
in In cancelReason in ('CUSTOMER', 'DECLINED')
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200

Examples:

Apply $filter to a property inside a expanded resource

$expand=organization($filter=name eq 'xxx')
$orderBy
string

Return sorted items based on property values. It can contains a comma-separated list of expressions. The expression may include the suffix "asc" for ascending or "desc" for descending, separated from the property name by one or more spaces. If "asc" or "desc" is not specified, the service MUST order by the specified property in ascending order. The sort order is the inherent order for the type of the property.

Examples:

Return all orders sorted by closedAt in descending order and a secondary sort order of updatedAt in ascending order.

$orderBy=closedAt desc,updatedAt
$expand
string

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 100,
  • "count": 100,
  • "@nextLink": "http://localhost:3005/orders?nextToken=xxx",
  • "@previousLink": "http://localhost:3005/orders?previousToken=xxx",
  • "value": [
    ]
}

Get orders for a user

Retrieves a list of orders for a user by queries.

This operation requires user is

  • a system admin
  • or the userId in the token matches the userId in the path
Authorizations:
(bearerAuthx-nb-fingerprint)
path Parameters
userId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for a user.

query Parameters
$skip
integer
Example: $skip=100

The maximum number of the items to skip (The Default value is 0).

$nextToken
string
Example: $nextToken=token

A unique token to get next batch of data. (base64 format)

$previousToken
string
Example: $previousToken=token

A unique token to get previous batch of data. (base64 format)

$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
in In cancelReason in ('CUSTOMER', 'DECLINED')
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200

Examples:

Apply $filter to a property inside a expanded resource

$expand=organization($filter=name eq 'xxx')
$orderBy
string

Return sorted items based on property values. It can contains a comma-separated list of expressions. The expression may include the suffix "asc" for ascending or "desc" for descending, separated from the property name by one or more spaces. If "asc" or "desc" is not specified, the service MUST order by the specified property in ascending order. The sort order is the inherent order for the type of the property.

Examples:

Return all orders sorted by closedAt in descending order and a secondary sort order of updatedAt in ascending order.

$orderBy=closedAt desc,updatedAt
$expand
string

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 100,
  • "count": 100,
  • "@nextLink": "http://localhost:3005/orders?nextToken=xxx",
  • "@previousLink": "http://localhost:3005/orders?previousToken=xxx",
  • "value": [
    ]
}

Get orders for an organization

Retrieves a list of orders for an organization by queries.

This operation requires user is

  • a system admin
  • or have owner/admin role in the organization
Authorizations:
(bearerAuthx-nb-fingerprint)
path Parameters
orgId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an organization.

query Parameters
$skip
integer
Example: $skip=100

The maximum number of the items to skip (The Default value is 0).

$nextToken
string
Example: $nextToken=token

A unique token to get next batch of data. (base64 format)

$previousToken
string
Example: $previousToken=token

A unique token to get previous batch of data. (base64 format)

$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
in In cancelReason in ('CUSTOMER', 'DECLINED')
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200

Examples:

Apply $filter to a property inside a expanded resource

$expand=organization($filter=name eq 'xxx')
$orderBy
string

Return sorted items based on property values. It can contains a comma-separated list of expressions. The expression may include the suffix "asc" for ascending or "desc" for descending, separated from the property name by one or more spaces. If "asc" or "desc" is not specified, the service MUST order by the specified property in ascending order. The sort order is the inherent order for the type of the property.

Examples:

Return all orders sorted by closedAt in descending order and a secondary sort order of updatedAt in ascending order.

$orderBy=closedAt desc,updatedAt
$expand
string

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 100,
  • "count": 100,
  • "@nextLink": "http://localhost:3005/orders?nextToken=xxx",
  • "@previousLink": "http://localhost:3005/orders?previousToken=xxx",
  • "value": [
    ]
}

Create a new order for an organization

Create a new order for an organization.

Authorizations:
(bearerAuthx-nb-fingerprint)
path Parameters
orgId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an organization.

query Parameters
$expand
string

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}
Request Body schema: application/json

Post an order request body.

cartId
string or null (nullableObjectId.field) ^[0-9a-z]{24}$

A 24 character hexadecimal string value.

checkoutId
string or null (nullableObjectId.field) ^[0-9a-z]{24}$

A 24 character hexadecimal string value.

required
Array of objects
required
object
status
string (orderStatus.field)
Enum: "PENDING" "ACCEPTED" "PROCESSING" "CLOSED" "CANCELED"

The status of the order. If omitted, status is set to PENDING by default:

  • PENDING: The order is pending.
  • ACCEPTED: The order is accepted.
  • PROCESSING: The order is in processing.
  • CLOSED: The order is completed successfully.
  • CANCELED: The order is canceled.
customFields
object (customFields.field)

Custom fields added to the customFields options in createOrderDefaultAdapter.

Responses

Request samples

Content type
application/json
Example
{
  • "items": [
    ],
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "organization": "0123456789ab0123456789ab",
  • "cart": { },
  • "checkout": { },
  • "lineItems": [
    ],
  • "currency": "JPY",
  • "subtotalPrice": 1000000,
  • "totalTax": 1000000,
  • "totalPrice": 1000000,
  • "customer": {
    },
  • "status": "PENDING",
  • "cancelReason": null,
  • "closedAt": "2022-01-01T00:00:000Z",
  • "canceledAt": "2022-01-01T00:00:000Z",
  • "customFields": {
    },
  • "createdAt": "2022-01-01T00:00:000Z",
  • "updatedAt": "2022-01-01T00:00:000Z"
}

Get an order

Retrieve a single order by id.

This operation requires user is

  • a system admin
  • or have owner/admin role in the organization
  • or user created this order
Authorizations:
(bearerAuthx-nb-fingerprint)
path Parameters
orgId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an organization.

orderId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an order.

query Parameters
$expand
string

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "organization": "0123456789ab0123456789ab",
  • "cart": { },
  • "checkout": { },
  • "lineItems": [
    ],
  • "currency": "JPY",
  • "subtotalPrice": 1000000,
  • "totalTax": 1000000,
  • "totalPrice": 1000000,
  • "customer": {
    },
  • "status": "PENDING",
  • "cancelReason": null,
  • "closedAt": "2022-01-01T00:00:000Z",
  • "canceledAt": "2022-01-01T00:00:000Z",
  • "customFields": {
    },
  • "createdAt": "2022-01-01T00:00:000Z",
  • "updatedAt": "2022-01-01T00:00:000Z"
}

Update an order

Update a single order by id partially. This operation allows for updating certain fields on the customer, or for updating the status of the order (including updates to CANCELLED or CLOSED).

See the request body below for information about which fields can be updated.

This operation requires user is

  • a system admin
  • or have owner/admin role in the organization
Authorizations:
(bearerAuthx-nb-fingerprint)
path Parameters
orgId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an organization.

orderId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an order.

query Parameters
$expand
string

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}
Request Body schema: application/json

Update an order request body.

canceledAt
string or null <date-time> (orderCanceledAt.field)

The date and time (ISO 8601 format) when the order was canceled. Returns null if the order isn't canceled.

cancelReason
string or null (orderCancelReason.field)
Enum: null "CUSTOMER" "INVENTORY" "DECLINED" "OTHER"

The reason why the order was canceled:

  • CUSTOMER: The customer canceled the order.
  • INVENTORY: Items in the order were not in inventory.
  • DECLINED: The order is in processing.
  • OTHER: A reason not in this list. Returns null if the order isn't canceled.
closedAt
string or null <date-time> (orderCanceledAt.field)

The date and time (ISO 8601 format) when the order was canceled. Returns null if the order isn't canceled.

customFields
object (customFields.field)

Custom fields added to the customFields options in createOrderDefaultAdapter.

object
status
string (orderStatus.field)
Enum: "PENDING" "ACCEPTED" "PROCESSING" "CLOSED" "CANCELED"

The status of the order:

  • PENDING: The order is pending.
  • ACCEPTED: The order is accepted.
  • PROCESSING: The order is in processing.
  • CLOSED: The order is completed successfully.
  • CANCELED: The order is canceled.

Responses

Request samples

Content type
application/json
Example
{
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "organization": "0123456789ab0123456789ab",
  • "cart": { },
  • "checkout": { },
  • "lineItems": [
    ],
  • "currency": "JPY",
  • "subtotalPrice": 1000000,
  • "totalTax": 1000000,
  • "totalPrice": 1000000,
  • "customer": {
    },
  • "status": "PENDING",
  • "cancelReason": null,
  • "closedAt": "2022-01-01T00:00:000Z",
  • "canceledAt": "2022-01-01T00:00:000Z",
  • "customFields": {
    },
  • "createdAt": "2022-01-01T00:00:000Z",
  • "updatedAt": "2022-01-01T00:00:000Z"
}

Delete an order

Delete a single order by id.

This operation requires user is

  • a system admin
  • or have owner/admin role in the organization

Only orders in a pending status can be deleted.

Authorizations:
(bearerAuthx-nb-fingerprint)
path Parameters
orgId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an organization.

orderId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an order.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get statistics for orders for an organization

Retrieves statistics for order counts aggregated for products on an organization. Returns the total count of orders for each product.

This operation requires user is

  • a system admin
  • or have owner/admin role in the organization
Authorizations:
(bearerAuthx-nb-fingerprint)
path Parameters
orgId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier for an organization.

productIds
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

Comma delimited unique ids of products to filter by.

Responses

Response samples

Content type
application/json
{
  • "organization": "0123456789ab0123456789ab",
  • "productId": "0123456789ab0123456789ab",
  • "count": 10
}