API docs by Redocly

Spoonbill API (4.0.0 - Demitasse)

Download OpenAPI specification:

Baskets

Endpoints for basket management.

Create Basket

Creates a new basket.

Required Grants:

  • spoonbill:basket:create
Request Body schema: application/json
required
user
string <= 100 characters
Default: null
status
integer
Default: 0
Enum: 0 1 2 3

The payment or cancellation status. Statuses correspond to Unpaid, Paid, Cancelled, and Abandoned respectively.

orderedOn
string <date-time>
Default: null
currency
integer
Default: 554

An ID code for a currency stored in Spoonbill. The default is NZD

dispatchedOn
string <date-time>
Default: null

Responses

Request samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null
}

Response samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "statusName": "Unpaid",
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get Basket

Gets a basket.

Required Grants:

  • spoonbill:basket:get
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
query Parameters
items
bool
Example: items=true

Includes basket items in the response

payments
bool
Example: payments=true

Includes basket payments in the response

details
bool
Example: details=true

Loads item details from DynamoDB

productTags
bool
Example: productTags=true

Loads tags for loaded products

productDetails
bool
Example: productDetails=true

Loads details for loaded products from DynamoDB

createdModified
bool
Example: createdModified=true

Includes the date fields Created and Modified on items

Responses

Response samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "statusName": "Unpaid",
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null,
  • "items": [
    ],
  • "products": [
    ],
  • "payments": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    }
}

Update Basket

Updates a basket.

Required Grants:

  • spoonbill:basket:update
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
user
string <= 100 characters
Default: null
status
integer
Default: 0
Enum: 0 1 2 3

The payment or cancellation status. Statuses correspond to Unpaid, Paid, Cancelled, and Abandoned respectively.

orderedOn
string <date-time>
Default: null
currency
integer
Default: 554

An ID code for a currency stored in Spoonbill. The default is NZD

dispatchedOn
string <date-time>
Default: null

Responses

Request samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null
}

Response samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "statusName": "Unpaid",
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Delete Basket

Deletes the basket's record, all related basket item records, all related payment records, and all related payment session records.

Cannot be used to delete baskets with the Paid status.

Required Grants:

  • spoonbill:basket:delete
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef

Responses

Comp Basket

Makes a basket a complimentary purchase.

This endpoint does three things:

  1. Changes the basket's status to Paid
  2. Marks all active payment sessions as canceled
  3. Adds a payment record to the basket for the full value of the basket, with the payment method as Comp

This action is only allowed if the basket's status is Unpaid.

The request body for this endpoint is optional, and may be any value or omitted entirely.

Required Grants:

  • spoonbill:basket:update
  • spoonbill:basketPayment:create

OR

  • spoonbill:basket:comp
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
shippingModifier
number
Default: 0

A modifier for the amount comped, intended to allow the deliberate inclusion of shipping cost in the comp payment record. This is added directly to the Amount field of the payment record.

transactionCode
string
Default: ""

A value for the TransactionCode field on the payment record

Responses

Request samples

Content type
application/json
{
  • "shippingModifier": 0,
  • "transactionCode": ""
}

Response samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "statusName": "Unpaid",
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null,
  • "items": [
    ],
  • "products": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Create Basket Item

Creates an item in the specified basket.

Required Grants:

  • spoonbill:basketItem:create
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
quantity
number
Default: 1
unit
string <= 20 characters
Default: "Item"

Responses

Request samples

Content type
application/json
{
  • "quantity": 1,
  • "unit": "Item"
}

Response samples

Content type
application/json
{
  • "basket": "5a30798c-c421-4b07-99ec-61709304307b",
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "quantity": 1,
  • "unit": "Item",
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Update Basket Item

Updates an item in the specified basket.

This cannot be used to update the product associated with a basket item.

Required Grants:

  • spoonbill:basketItem:update
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
{item}
required
string <uuid>
Request Body schema: application/json
required
quantity
number
Default: 1
unit
string <= 20 characters
Default: "Item"

Responses

Request samples

Content type
application/json
{
  • "quantity": 1,
  • "unit": "Item"
}

Response samples

Content type
application/json
{
  • "basket": "5a30798c-c421-4b07-99ec-61709304307b",
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "quantity": 1,
  • "unit": "Item",
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Delete Basket Item

Deletes an item in the specified basket.

Required Grants:

  • spoonbill:basketItem:delete
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
{item}
required
string <uuid>

Responses

Start a Payment Session

Begins a payment session for the specified basket.

Users may only start payment sessions for their own baskets, and only on baskets who's status is 'Unpaid' (0).

ApprovedCallback and CanceledCallback are more specific variants of Callback, and only required if Callback is not defined. Conversely, Callback is only required if ApprovedCallback and CanceledCallback are not defined. If all three are defined, ApprovedCallback and CanceledCallback take precedence.

Starting a session does four things:

  1. Stats a payment session with a third party provider*
  2. Cancels any existing payment session records
  3. Creates a new payment session record with;
    1. An expiry date
    2. A basket digest that will be used to check that the basket is not edited during the payment session
  4. Creates a new incomplete payment record, with links to both the basket and the payment session**

*If the specified credit to be used is greater then or equal to the cost of the basket, or the payment type is Credit, the basket will be paid for entirely via credit, and no 3rd party payment session will be created.

**If the user is using credit as a part of the payment session, a second payment record for the credit will be created. This record will not be marked as completed until the main payment record is also completed.

The requirements/process for the shipping price will change depending on the settings in the tenancy profile. If ShippingPriceStoredProcedureName is configured, a stored procedure will be invoked to calculate the shipping price from within Spoonbill, and will then be added to the calculated price of the basket.

path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
useCredit
number
Default: 0

The amount of the user's credit to be expended on this basket. The user's credit will be checked to determine if enough credit is available.

callback
string

The URL the user will be directed to after completing the 3rd party checkout process.

approvedCallback
string

The URL the user will be directed to after successfully completing the 3rd party checkout process.

canceledCallback
string

The URL the user will be directed to after failing to complete the 3rd party checkout process.

method
string

The payment method to use. Currently, the only legal value is PxPay.

shippingMeta1
string

Optional field used in calculating shipping. Use is determined by tenancy-specific stored procedure.

shippingMeta2
string

Optional field used in calculating shipping. Use is determined by tenancy-specific stored procedure.

shippingMeta3
string

Optional field used in calculating shipping. Use is determined by tenancy-specific stored procedure.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "paid": true,
  • "href": "string"
}

End a Payment Session

Ends a payment session.

The session may not complete if the basket has been modified since the session was created. It may also fail if the session has expired, or was canceled by the user starting another session.

Ending a payment session does several things:

  1. The payment session will be checked to determine if it is active and not expired
    1. If the payment session is expired, its status may be updated accordingly
  2. The basket digest will be checked to determine if the basket was modified since the start of the payment session
  3. The 3rd party payment service will be checked to determine the result of the session
  4. The payment session will be marked completed/declined/failed/failedDigestChanged
  5. If completed;
    1. The basket will be marked as paid
    2. The basket will have it's ordered on field updated
    3. The payment record for the session will be marked as paid
    4. If it exists, the credit payment record for the session will be marked as paid, and the user's credit history will be updated accordingly

If the user chose to use credit, and some change has caused them to not have enough credit at this point, the payment will partially complete. The main payment record for the 3rd party payment method will mark as completed, while the payment record for the credit — and the basket itself — will remain unpaid.

The session ID and basket ID will automatically be included in the query string of the callback URL used when creating the session (...?fcPaymentSession=...&fcBasket=...).

path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
{session}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
pxPayUserId
string

Field included in the query string of the callback URL when using PX Pay as the session payment method. Included as userid=....

pxPayResult
string

Field included in the query string of the callback URL when using PX Pay as the session payment method. Included as result=.... Required in order to validate the PX Pay session result.

Responses

Request samples

Content type
application/json
{
  • "pxPayUserId": "Firecrest_RestDev",
  • "pxPayResult": "0000030008163607036c4f777b375696"
}

Response samples

Content type
{
  • "success": true,
  • "message": "Payment completed"
}

Query Baskets

Queries all baskets.

Leaving a field null or undefined in the request body applies no filter to that field. For dates, specific date filters take precedence over date range filters, which take precedence over 'is null' filters. String fields are filtered with SQL-style LIKE comparison.

Required Grants:

  • spoonbill:basket:get
  • spoonbill:basket:list
Request Body schema: application/json
required
user
string

SQL LIKE style comparison filter

statusIn
Array of integers
orderedOn
string <date-time>
orderedBefore
string <date-time>

Range filter on OrderedOn

orderedAfter
string <date-time>

Range filter on OrderedOn

orderedOnIsNull
boolean

Null state filter on OrderedOn

currencyIn
Array of integers
dispatchedOn
string <date-time>
dispatchedBefore
string <date-time>

Range filter on DispatchedOn

dispatchedAfter
string <date-time>

Range filter on DispatchedOn

dispatchedOnIsNull
boolean

Null state filter on DispatchedOn

orderBy
string

A SQL order by clause. Automatically stripped of any text other then column names, ASC and DESC, and commas

page
integer
Default: 0
limit
integer
Default: 20

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "statusIn": [
    ],
  • "orderedOn": "2019-08-24T14:15:22Z",
  • "orderedBefore": "2019-08-24T14:15:22Z",
  • "orderedAfter": "2019-08-24T14:15:22Z",
  • "orderedOnIsNull": true,
  • "currencyIn": [
    ],
  • "dispatchedOn": "2019-08-24T14:15:22Z",
  • "dispatchedBefore": "2019-08-24T14:15:22Z",
  • "dispatchedAfter": "2019-08-24T14:15:22Z",
  • "dispatchedOnIsNull": true,
  • "orderBy": "string",
  • "page": 0,
  • "limit": 20
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "maxAvailableItems": 1
}

Baskets - Self Service

Endpoints for users to manage their own baskets.

List User Baskets

Gets all baskets for the current user.

query Parameters
items
bool
Example: items=true

Includes basket items in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create User Basket

Creates a new basket for the current user.

Only the currency field can be specified. The user field is automatically set to the current user.

query Parameters
items
bool
Example: items=true

Includes basket items in the response

Request Body schema: application/json
required
currency
integer
Default: 554

An ID code for a currency stored in Spoonbill. The default is NZD

Responses

Request samples

Content type
application/json
{
  • "currency": 554
}

Response samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "statusName": "Unpaid",
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get User's Basket

Gets a specific basket belonging to the current user.

path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
query Parameters
items
bool
Example: items=true

Includes basket items in the response

payments
bool
Example: payments=true

Includes basket payments in the response

Responses

Response samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "statusName": "Unpaid",
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null,
  • "items": [
    ],
  • "products": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Update User's Own Basket

Updates the user's own basket.

Users may only update their own baskets, and only baskets who's status is not 'Paid' (1). Only the status (excluding Paid) and currency fields can be updated.

Required Grants:

  • None
path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
status
integer
Default: 0
Enum: 0 2 3

The payment or cancellation status. Users cannot set status to Paid (1).

currency
integer
Default: 554

An ID code for a currency stored in Spoonbill. The default is NZD

Responses

Request samples

Content type
application/json
{
  • "status": 0,
  • "currency": 554
}

Response samples

Content type
application/json
{
  • "user": "test@acme.org.nz",
  • "status": 0,
  • "statusName": "Unpaid",
  • "orderedOn": null,
  • "currency": 554,
  • "dispatchedOn": null,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Delete User's Basket

Deletes a specific basket belonging to the current user.

The basket must have the Unpaid status (0), or else the operation silently fails.

path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef

Responses

Create User's Basket Item

Creates an item in the specified basket belonging to the current user.

Only baskets with the status 0 (Unpaid) can be edited in this way.

path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
quantity
number
Default: 1
unit
string <= 20 characters
Default: "Item"

Responses

Request samples

Content type
application/json
{
  • "quantity": 1,
  • "unit": "Item"
}

Response samples

Content type
application/json
{
  • "basket": "5a30798c-c421-4b07-99ec-61709304307b",
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "quantity": 1,
  • "unit": "Item",
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Update User's Basket Item

Updates an item in the specified basket belonging to the current user.

This cannot be used to update the product associated with a basket item.

Only baskets with the status 0 (Unpaid) can be edited in this way.

path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
{item}
required
string <uuid>
Request Body schema: application/json
required
quantity
number
Default: 1
unit
string <= 20 characters
Default: "Item"

Responses

Request samples

Content type
application/json
{
  • "quantity": 1,
  • "unit": "Item"
}

Response samples

Content type
application/json
{
  • "basket": "5a30798c-c421-4b07-99ec-61709304307b",
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "quantity": 1,
  • "unit": "Item",
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Delete User's Basket Item. Items cannot be deleted if the basket is in any status other then 'Unpaid'.

Deletes an item in the specified basket belonging to the current user.

Only baskets with the status 0 (Unpaid) can be edited in this way.

path Parameters
{basket}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
{item}
required
string <uuid>

Responses

Credit

Endpoints for user credit management.

Get User Credit

Gets the specified user's currently available credit.

If loading for all currencies, a list is returned, which depending on the user's credit history may be empty. If loading for a specific currency, a single item will be returned, which will be a default item if no records exist.

Required Grants:

  • spoonbill:credit:get
path Parameters
{user}
required
string <email>
Example: test1@acme.org.nz
query Parameters
currency
integer
Example: currency=554

Loads only the specified currency

Responses

Response samples

Content type
[
  • {
    }
]

Add credit log

Creates a new credit log entry for the specified user

Required Grants:

  • spoonbill:credit:update
path Parameters
{user}
required
string <email>
Example: test1@acme.org.nz
query Parameters
currency
integer
Example: currency=554

Loads only the specified currency

Request Body schema: application/json
timestamp
string <date-time>

Defaults to the current time

basketPayment
string or null <uuid>
note
string
maxLength
any
amount
number
currency
integer
Default: 554

An ID code for a currency stored in Spoonbill. The default is NZD

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-08-24T14:15:22Z",
  • "basketPayment": "a5952df3-d249-4619-8670-bc9dc5449ad5",
  • "note": "string",
  • "maxLength": null,
  • "amount": 0,
  • "currency": 554
}

Response samples

Content type
application/json
{
  • "timestamp": "2019-08-24T14:15:22Z",
  • "basketPayment": "a5952df3-d249-4619-8670-bc9dc5449ad5",
  • "note": "string",
  • "maxLength": null,
  • "user": "test@acme.org.nz",
  • "amount": 0,
  • "currency": 554,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get User Credit History

Gets the specified user's credit history.

Returns a list of credit log records, ordered by time stamp, then by currency, ascending.

Required Grants:

  • spoonbill:credit:get
path Parameters
{user}
required
string <email>
Example: test1@acme.org.nz
query Parameters
currency
integer
Example: currency=554

Loads only the specified currency

from
string <date-time>

Date range limit

to
string <date-time>

Date range limit

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Credit - Self Service

Endpoints for users to view their own credit.

Get User Credit (Self)

Gets the currently available credit for the current user.

If loading for all currencies, a list is returned, which depending on the user's credit history may be empty. If loading for a specific currency, a single item will be returned, which will be a default item if no records exist.

path Parameters
{user}
required
string <email>
Example: test1@acme.org.nz
query Parameters
currency
integer
Example: currency=554

Loads only the specified currency

Responses

Response samples

Content type
[
  • {
    }
]

Get User Credit History (Self)

Gets credit history for the current user.

Returns a list of credit log records, ordered by time stamp, then by currency, ascending.

path Parameters
{user}
required
string <email>
Example: test1@acme.org.nz
query Parameters
currency
integer
Example: currency=554

Loads only the specified currency

from
string <date-time>

Date range limit

to
string <date-time>

Date range limit

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Products

Endpoints for product management.

Create Product

Creates a new product.

Required Grants: (allows conditional grants)

  • spoonbill:product:create
Request Body schema: application/json
required
name
string <= 100 characters
Default: ""
productCode
string <= 100 characters
Default: ""
productType
integer
Default: 0
Enum: 0 1 2 3

Product types correspond to SingleItem, Bundle, Recurring, and RecurringBundle respectively.

Bundles refer to products that are a collection of other products. Recurring products would refer to things like subscriptions or other ongoing services.

productTypeName
string
Enum: "SingleItem" "Bundle" "Recurring" "RecurringBundle"

The string form of the product's ProductType. This field is only used in API output.

sku
string <= 100 characters
Default: ""
shortDescription
string <= 250 characters
Default: ""
primaryImage
string <= 100 characters
Default: "/assets/egg.png"
weightKg
double
Default: 0.06
includePostage
bool
Default: false
consignable
bool
Default: true

'Consignable' here means that the product is a physical item. For example a VideoHub livestream would not be consignable.

supplier
string <= 100 characters
Default: ""
public
bool
Default: false
archived
bool
Default: false
details
object
Default: null

Any JSON that can be stored in DynamoDB

tags
Array of strings[ items <= 100 characters ]
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": "A Single Egg",
  • "productCode": "3GG",
  • "productType": 0,
  • "productTypeName": "SingleItem",
  • "sku": "egg",
  • "shortDescription": "It's an egg",
  • "primaryImage": "/assets/egg.png",
  • "weightKg": 0.06,
  • "includePostage": false,
  • "consignable": true,
  • "supplier": "",
  • "public": true,
  • "archived": false,
  • "details": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "A Single Egg",
  • "productCode": "3GG",
  • "productType": 0,
  • "productTypeName": "SingleItem",
  • "sku": "egg",
  • "shortDescription": "It's an egg",
  • "primaryImage": "/assets/egg.png",
  • "weightKg": 0.06,
  • "includePostage": false,
  • "consignable": true,
  • "supplier": "",
  • "public": true,
  • "archived": false,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    },
  • "tags": [
    ]
}

Get Product

Gets a product.

Required Grants: (allows conditional grants)

  • spoonbill:product:get
query Parameters
tags
bool
Example: tags=true

Loads item tags

details
bool
Example: details=true

Loads item details from DynamoDB

createdModified
bool
Example: createdModified=true

Includes the date fields Created and Modified on items

Responses

Response samples

Content type
application/json
{
  • "name": "A Single Egg",
  • "productCode": "3GG",
  • "productType": 0,
  • "productTypeName": "SingleItem",
  • "sku": "egg",
  • "shortDescription": "It's an egg",
  • "primaryImage": "/assets/egg.png",
  • "weightKg": 0.06,
  • "includePostage": false,
  • "consignable": true,
  • "supplier": "",
  • "public": true,
  • "archived": false,
  • "currentPrice": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    },
  • "tags": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z"
}

Update Product

Updates a product.

If tags is set, all tags for this product will be overwritten.

Required Grants: (allows conditional grants)

  • spoonbill:product:update
Request Body schema: application/json
required
name
string <= 100 characters
Default: ""
productCode
string <= 100 characters
Default: ""
productType
integer
Default: 0
Enum: 0 1 2 3

Product types correspond to SingleItem, Bundle, Recurring, and RecurringBundle respectively.

Bundles refer to products that are a collection of other products. Recurring products would refer to things like subscriptions or other ongoing services.

productTypeName
string
Enum: "SingleItem" "Bundle" "Recurring" "RecurringBundle"

The string form of the product's ProductType. This field is only used in API output.

sku
string <= 100 characters
Default: ""
shortDescription
string <= 250 characters
Default: ""
primaryImage
string <= 100 characters
Default: "/assets/egg.png"
weightKg
double
Default: 0.06
includePostage
bool
Default: false
consignable
bool
Default: true

'Consignable' here means that the product is a physical item. For example a VideoHub livestream would not be consignable.

supplier
string <= 100 characters
Default: ""
public
bool
Default: false
archived
bool
Default: false
details
object
Default: null

Any JSON that can be stored in DynamoDB

tags
Array of strings[ items <= 100 characters ]
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": "A Single Egg",
  • "productCode": "3GG",
  • "productType": 0,
  • "productTypeName": "SingleItem",
  • "sku": "egg",
  • "shortDescription": "It's an egg",
  • "primaryImage": "/assets/egg.png",
  • "weightKg": 0.06,
  • "includePostage": false,
  • "consignable": true,
  • "supplier": "",
  • "public": true,
  • "archived": false,
  • "details": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "A Single Egg",
  • "productCode": "3GG",
  • "productType": 0,
  • "productTypeName": "SingleItem",
  • "sku": "egg",
  • "shortDescription": "It's an egg",
  • "primaryImage": "/assets/egg.png",
  • "weightKg": 0.06,
  • "includePostage": false,
  • "consignable": true,
  • "supplier": "",
  • "public": true,
  • "archived": false,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    },
  • "tags": [
    ]
}

Archive Product

Archives a product.

Required Grants: (allows conditional grants)

  • spoonbill:product:update

Responses

Response samples

Content type
text/plain
Unauthorized

Unarchive Product

Unarchives a product.

Required Grants: (allows conditional grants)

  • spoonbill:product:update

Responses

Response samples

Content type
text/plain
Unauthorized

Get Product Price History

Gets a product's full price history.

This endpoint uses the product item to check conditional grants, not the price history item.

Required Grants: (allows conditional grants)

  • spoonbill:product:getPrice

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Product Price History

Applies a suite of changes to a product's price history by creating, updating, and deleting items.

This endpoint uses the product item to check conditional grants, not the price history item.

Required Grants: (allows conditional grants)

  • spoonbill:product:updatePrice
Request Body schema: application/json
required
Array of objects (Price History - Input)
Array of objects (Price History - Input)
delete
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "create": [
    ],
  • "update": [
    ],
  • "delete": [
    ]
}

Response samples

Content type
application/json
{
  • "created": [
    ]
}

Query Products

Provides a filtered list of all products.

String-based filters use SQL LIKE syntax, and thus are case-insensitive and may use wildcards (_ for single characters, % for variable). Setting the weightKg filter will override the weightKgMin and weightKgMax filters. In all cases null values will apply no filter at all.

Required Grants: (allows conditional grants)

  • spoonbill:product:get
  • spoonbill:product:list
query Parameters
tags
bool
Example: tags=true

Loads item tags

details
bool
Example: details=true

Loads item details from DynamoDB

Request Body schema: application/json
required
name
string
Default: null
productCode
string
Default: null
productType
int
Default: null
sku
string
Default: null
shortDescription
string
Default: null
primaryImage
string
Default: null
weightKg
number
Default: null
weightKgMin
number
Default: null
weightKgMax
number
Default: null
includePostage
bool
Default: null
consignable
bool
Default: null
supplier
string
Default: null
public
bool
Default: null
archived
bool
Default: null
created
string <date-time>
Default: null
createdAfter
string <date-time>
Default: null
createdBefore
string <date-time>
Default: null
modified
string <date-time>
Default: null
modifiedAfter
string <date-time>
Default: null
modifiedBefore
string <date-time>
Default: null
object
orderBy
string

A SQL order by clause. Automatically stripped of any text other then column names, ASC and DESC, and commas

page
integer

The nth page to return (zero-indexed)

limit
integer

The number of items per page

Responses

Request samples

Content type
application/json
{
  • "name": "%egg%",
  • "weightKgMin": 0.05,
  • "weightKgMax": 0.07
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "maxAvailableItems": 1
}

Products - Public

Public endpoints for product access without authentication.

Get Product - Public

Gets a public product.

In the response, the private subfield of the details field will be removed, if it exists.

query Parameters
tags
bool
Example: tags=true

Loads item tags

details
bool
Example: details=true

Loads item details from DynamoDB

Responses

Response samples

Content type
application/json
{
  • "name": "A Single Egg",
  • "productCode": "3GG",
  • "productType": 0,
  • "productTypeName": "SingleItem",
  • "sku": "egg",
  • "shortDescription": "It's an egg",
  • "primaryImage": "/assets/egg.png",
  • "weightKg": 0.06,
  • "includePostage": false,
  • "consignable": true,
  • "supplier": "",
  • "public": true,
  • "archived": false,
  • "currentPrice": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    },
  • "tags": [
    ]
}

Query Products - Public

Provides a filtered list of all public products.

String-based filters use SQL LIKE syntax, and thus are case-insensitive and may use wildcards (_ for single characters, % for variable). Setting the weightKg filter will override the weightKgMin and weightKgMax filters. In all cases null values will apply no filter at all.

In the response, the private subfield of the details field will be removed, if it exists.

query Parameters
tags
bool
Example: tags=true

Loads item tags

details
bool
Example: details=true

Loads item details from DynamoDB

Request Body schema: application/json
required
name
string
Default: null
productCode
string
Default: null
productType
int
Default: null
sku
string
Default: null
shortDescription
string
Default: null
primaryImage
string
Default: null
weightKg
number
Default: null
weightKgMin
number
Default: null
weightKgMax
number
Default: null
includePostage
bool
Default: null
consignable
bool
Default: null
supplier
string
Default: null
archived
bool
Default: null
object
orderBy
Array of strings
page
integer

The nth page to return (zero-indexed)

limit
integer

The number of items per page

Responses

Request samples

Content type
application/json
{
  • "name": "%egg%",
  • "weightKgMin": 0.05,
  • "weightKgMax": 0.07
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "maxAvailableItems": 1
}

Shipping

Endpoints for shipping price data management.

Get Shipping Price Data

Gets all shipping price data for the tenancy.

Shipping price data is used as a configuration source when calculating basket shipping via stored procedure. As such, the exact function of each field is determined by the stored procedure used by that tenancy.

Required Grants:

  • spoonbill:shippingPriceData:get

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set Shipping Price Data

Sets all shipping price data for the tenancy.

Shipping price data is used as a configuration source when calculating basket shipping via stored procedure. As such, the exact function of each field is determined by the stored procedure used by that tenancy.

Required Grants:

  • spoonbill:shippingPriceData:update
Request Body schema: application/json
required
Array
currency
integer
Default: 554

An ID code for a currency stored in Spoonbill. The default is NZD

amount
number
Default: 0
customNumber1
number or null
Default: null
customNumber2
number or null
Default: null
customNumber3
number or null
Default: null
customString1
string or null <= 500 characters
Default: null
customString2
string or null <= 500 characters
Default: null
customString3
string or null <= 500 characters
Default: null

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Shipments

Endpoints for shipment management.

Create Shipment

Creates a new shipment record.

Required Grants:

  • spoonbill:shipment:create
Request Body schema: application/json
required
freightCode
string <= 100 characters
Default: ""
freightCompany
string or null <= 100 characters
consignment
string or null <= 100 characters
supplier
string or null <uuid>
billOfLading
string or null <= 100 characters
date
string <date-time>
Default: "now"
estimatedDeliveryDate
string or null <date-time>
freightPrice
number
Default: 0
freightWeightKG
number
Default: 0
cargoLink
string or null <= 500 characters
archived
boolean
Default: false
details
object
Default: null

Any JSON that can be stored in DynamoDB

tags
Array of strings[ items <= 100 characters ]
Default: null

Responses

Request samples

Content type
application/json
{
  • "freightCode": "",
  • "freightCompany": "string",
  • "consignment": "string",
  • "supplier": "acc345c7-457d-43bb-ac95-81572c2199bb",
  • "billOfLading": "string",
  • "date": "now",
  • "estimatedDeliveryDate": "2019-08-24T14:15:22Z",
  • "freightPrice": 0,
  • "freightWeightKG": 0,
  • "cargoLink": "string",
  • "archived": false,
  • "details": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "freightCode": "",
  • "freightCompany": "string",
  • "consignment": "string",
  • "supplier": "acc345c7-457d-43bb-ac95-81572c2199bb",
  • "billOfLading": "string",
  • "date": "now",
  • "estimatedDeliveryDate": "2019-08-24T14:15:22Z",
  • "freightPrice": 0,
  • "freightWeightKG": 0,
  • "cargoLink": "string",
  • "archived": false,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    },
  • "tags": [
    ]
}

Get Shipment

Gets a single shipment record by ID.

Required Grants:

  • spoonbill:shipment:get
path Parameters
{shipment}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
query Parameters
details
bool
Example: details=true

Loads item details from DynamoDB

Responses

Response samples

Content type
application/json
{
  • "freightCode": "",
  • "freightCompany": "string",
  • "consignment": "string",
  • "supplier": "acc345c7-457d-43bb-ac95-81572c2199bb",
  • "billOfLading": "string",
  • "date": "now",
  • "estimatedDeliveryDate": "2019-08-24T14:15:22Z",
  • "freightPrice": 0,
  • "freightWeightKG": 0,
  • "cargoLink": "string",
  • "archived": false,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    },
  • "tags": [
    ]
}

Update Shipment

Updates a shipment record.

Required Grants:

  • spoonbill:shipment:update
path Parameters
{shipment}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef
Request Body schema: application/json
required
freightCode
string <= 100 characters
Default: ""
freightCompany
string or null <= 100 characters
consignment
string or null <= 100 characters
supplier
string or null <uuid>
billOfLading
string or null <= 100 characters
date
string <date-time>
Default: "now"
estimatedDeliveryDate
string or null <date-time>
freightPrice
number
Default: 0
freightWeightKG
number
Default: 0
cargoLink
string or null <= 500 characters
archived
boolean
Default: false
details
object
Default: null

Any JSON that can be stored in DynamoDB

tags
Array of strings[ items <= 100 characters ]
Default: null

Responses

Request samples

Content type
application/json
{
  • "freightCode": "",
  • "freightCompany": "string",
  • "consignment": "string",
  • "supplier": "acc345c7-457d-43bb-ac95-81572c2199bb",
  • "billOfLading": "string",
  • "date": "now",
  • "estimatedDeliveryDate": "2019-08-24T14:15:22Z",
  • "freightPrice": 0,
  • "freightWeightKG": 0,
  • "cargoLink": "string",
  • "archived": false,
  • "details": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "freightCode": "",
  • "freightCompany": "string",
  • "consignment": "string",
  • "supplier": "acc345c7-457d-43bb-ac95-81572c2199bb",
  • "billOfLading": "string",
  • "date": "now",
  • "estimatedDeliveryDate": "2019-08-24T14:15:22Z",
  • "freightPrice": 0,
  • "freightWeightKG": 0,
  • "cargoLink": "string",
  • "archived": false,
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    },
  • "tags": [
    ]
}

Archive Shipment

Archives a shipment by setting its archived flag to true.

Required Grants:

  • spoonbill:shipment:update
path Parameters
{shipment}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef

Responses

Response samples

Content type
text/plain
Not Found

Unarchive Shipment

Unarchives a shipment by setting its archived flag to false.

Required Grants:

  • spoonbill:shipment:update
path Parameters
{shipment}
required
string <uuid>
Example: 01324567-89ab-cdef-0123-456789abcdef

Responses

Response samples

Content type
text/plain
Not Found

Query Shipments

Queries shipment records with filtering and pagination.

String-based filters use SQL LIKE syntax. All filter parameters are optional.

Required Grants:

  • spoonbill:shipment:list
  • spoonbill:shipment:get
query Parameters
details
bool
Example: details=true

Loads item details from DynamoDB

Request Body schema: application/json
required
supplier
string or null <uuid>

Filter by supplier ID

freightCompany
string or null

Filter by freight company name (SQL LIKE)

dateFrom
string or null <date-time>

Filter shipments on or after this date

dateTo
string or null <date-time>

Filter shipments on or before this date

estimatedDeliveryFrom
string or null <date-time>

Filter by estimated delivery on or after this date

estimatedDeliveryTo
string or null <date-time>

Filter by estimated delivery on or before this date

archived
boolean or null

Filter by archived status

orderBy
string or null
Default: "Date DESC, ID ASC"

A SQL order by clause. Automatically stripped of any text other than column names, ASC and DESC, and commas. Defaults to "Date DESC"

page
integer
Default: 0

Zero-indexed page number

limit
integer
Default: 20

Number of items per page

Responses

Request samples

Content type
application/json
{
  • "supplier": null,
  • "freightCompany": "Shipping%",
  • "dateFrom": "2024-01-01T00:00:00Z",
  • "dateTo": "2024-12-31T23:59:59Z",
  • "estimatedDeliveryFrom": null,
  • "estimatedDeliveryTo": null,
  • "archived": null,
  • "orderBy": "Date DESC",
  • "page": 0,
  • "limit": 20
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "maxAvailableItems": 0
}

Stock

Endpoints for stock management.

Create Stock

Creates a new stock record.

This endpoint automatically creates an initial stock allocation/location with type/location "Initial" and quantity equal to the stock's initial quantity. If an initial allocation/location is provided via the allocations/locations property, it will be used instead, through the quantity will be overwritten by the stock's initialQuantity.

Required Grants:

  • spoonbill:stock:create
Request Body schema: application/json
required
product
string <uuid>
initialQuantity
number
unit
string <= 100 characters
Default: "Item"
order
string or null <uuid>
shipment
string or null <uuid>
shipmentStatus
integer
Enum: 0 1
archived
boolean
Default: false
Array of objects (Stock Allocation - Input)

Optional. If provided, the first allocation will be used as the initial allocation instead of creating a default one.

Array of objects (Stock Location - Input)

Optional. If provided, the first location will be used as the initial location instead of creating a default one.

details
object
Default: null

Any JSON that can be stored in DynamoDB

tags
Array of strings[ items <= 100 characters ]
Default: null

Responses

Request samples

Content type
application/json
{
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "initialQuantity": 0,
  • "unit": "Item",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "shipment": "040451d7-03ba-4b1e-94f7-5cacc36efb36",
  • "shipmentStatus": 0,
  • "archived": false,
  • "allocations": [
    ],
  • "locations": [
    ],
  • "details": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "initialQuantity": 0,
  • "unit": "Item",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "shipment": "040451d7-03ba-4b1e-94f7-5cacc36efb36",
  • "shipmentStatus": 0,
  • "archived": false,
  • "allocations": [
    ],
  • "locations": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    }
}

Get Stock

Gets a single stock record by ID.

Required Grants:

  • spoonbill:stock:get
path Parameters
{id}
required
string <uuid>
query Parameters
details
bool
Example: details=true

Loads item details from DynamoDB

createdModified
bool
Example: createdModified=true

Includes the date fields Created and Modified on items

allocations
bool
Example: allocations=true

Includes stock allocations in the response

locations
bool
Example: locations=true

Includes stock locations in the response

Responses

Response samples

Content type
application/json
{
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "initialQuantity": 0,
  • "unit": "Item",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "shipment": "040451d7-03ba-4b1e-94f7-5cacc36efb36",
  • "shipmentStatus": 0,
  • "archived": false,
  • "allocations": [
    ],
  • "locations": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    }
}

Update Stock

Updates a stock record.

Required Grants:

  • spoonbill:stock:update
path Parameters
{id}
required
string <uuid>
Request Body schema: application/json
required
product
string <uuid>
initialQuantity
number
unit
string <= 100 characters
Default: "Item"
order
string or null <uuid>
shipment
string or null <uuid>
shipmentStatus
integer
Enum: 0 1
archived
boolean
Default: false
details
object
Default: null

Any JSON that can be stored in DynamoDB

tags
Array of strings[ items <= 100 characters ]
Default: null

Responses

Request samples

Content type
application/json
{
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "initialQuantity": 0,
  • "unit": "Item",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "shipment": "040451d7-03ba-4b1e-94f7-5cacc36efb36",
  • "shipmentStatus": 0,
  • "archived": false,
  • "details": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "product": "e0588024-d851-42d5-ab9f-1b664ef352d4",
  • "initialQuantity": 0,
  • "unit": "Item",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "shipment": "040451d7-03ba-4b1e-94f7-5cacc36efb36",
  • "shipmentStatus": 0,
  • "archived": false,
  • "allocations": [
    ],
  • "locations": [
    ],
  • "tenancy": "acme.org.nz.core",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "details": {
    }
}

Archive Stock

Archives a stock record by setting its archived flag to true.

Required Grants:

  • spoonbill:stock:update
path Parameters
{id}
required
string <uuid>

Responses

Response samples

Content type
text/plain
Not Found

Unarchive Stock

Unarchives a stock record by setting its archived flag to false.

Required Grants:

  • spoonbill:stock:update
path Parameters
{id}
required
string <uuid>

Responses

Response samples

Content type
text/plain
Not Found

Override Stock Allocation Quantity

Manually overrides the quantity of a specific stock allocation by creating a new allocation record and linking it via a reallocation record.

This endpoint validates that the allocation belongs to the specified stock before making changes.

Required Grants:

  • spoonbill:stockAllocation:override
path Parameters
{id}
required
string <uuid>
{allocation}
required
string <uuid>
Request Body schema: application/json
required
quantity
required
number

The new quantity for the allocation

note
string or null <= 255 characters

Optional note for the reallocation. Defaults to "Manual Correction"

Responses

Request samples

Content type
application/json
{
  • "quantity": 50,
  • "note": "Adjusted quantity"
}

Response samples

Content type
application/json
{
  • "stock": "3ad27da3-adc9-4632-966e-f8e829b4adbd",
  • "type": "string",
  • "reference": "string",
  • "quantity": 0,
  • "timestamp": "2019-08-24T14:15:22Z",
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Apply Stock Reallocations

Applies multiple stock reallocations in a single transaction. Creates new allocation records and links them to source allocations via reallocation records.

This endpoint validates that all source allocations belong to the specified stock and that quantity totals match between sources and new allocations.

Required Grants:

  • spoonbill:stockAllocation:reallocate
path Parameters
{id}
required
string <uuid>
Request Body schema: application/json
required
Array
required
object
required
Array of objects

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Update Stock Location Details

Updates the location details of a specific stock location by creating a new location record and linking it via a relocation record.

This endpoint validates that the location belongs to the specified stock before making changes.

Required Grants:

  • spoonbill:stockLocation:override
path Parameters
{id}
required
string <uuid>
{location}
required
string <uuid>
Request Body schema: application/json
required
location
required
string <= 250 characters

The new location name

quantity
number or null

Optional quantity for the location. If not provided, keeps existing quantity

note
string or null <= 255 characters

Optional note for the relocation. Defaults to "Manual Update"

Responses

Request samples

Content type
application/json
{
  • "location": "Warehouse B",
  • "quantity": 10,
  • "note": "Moved to new warehouse"
}

Response samples

Content type
application/json
{
  • "stock": "3ad27da3-adc9-4632-966e-f8e829b4adbd",
  • "location": "string",
  • "quantity": 0,
  • "timestamp": "2019-08-24T14:15:22Z",
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Apply Stock Relocations

Applies multiple stock relocations in a single transaction. Creates new location records and links them to source locations via relocation records.

This endpoint validates that all source locations belong to the specified stock.

Required Grants:

  • spoonbill:stockLocation:relocate
path Parameters
{id}
required
string <uuid>
Request Body schema: application/json
required
Array
required
object
required
Array of objects

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Query Stock

Queries stock records with filtering and pagination.

Required Grants:

  • spoonbill:stock:list
  • spoonbill:stock:get
query Parameters
tags
bool
Example: tags=true

Loads item tags

details
bool
Example: details=true

Loads item details from DynamoDB

allocations
bool
Example: allocations=true

Includes stock allocations in the response

locations
bool
Example: locations=true

Includes stock locations in the response

Request Body schema: application/json
required
product
string or null <uuid>
initialQuantityMin
number or null
initialQuantityMax
number or null
unit
string or null
order
string or null <uuid>
shipment
string or null <uuid>
shipmentStatusIn
Array of integers or null
archived
boolean or null
page
integer
Default: 0
limit
integer
Default: 20
orderBy
string or null

Responses

Request samples

Content type
application/json
{
  • "product": "4b6344d0-a4f9-46f2-be5b-435968c5f976",
  • "initialQuantityMin": 0,
  • "initialQuantityMax": 1000,
  • "unit": "Item",
  • "archived": false,
  • "page": 0,
  • "limit": 20,
  • "orderBy": "ID"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "maxAvailableItems": 0
}

Stock - Allocation-Locations

Endpoints for managing the relationship between stock allocations and locations.

Get Allocation Locations

Gets all locations associated with a specific stock allocation.

This endpoint validates that the allocation belongs to the specified stock.

Required Grants:

  • spoonbill:stock:get
path Parameters
{id}
required
string <uuid>
{allocation}
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set Allocation Location

Sets or updates a specific location for a stock allocation.

This endpoint validates that the allocation belongs to the specified stock before making changes.

Required Grants:

  • spoonbill:stockAllocationLocation:override
path Parameters
{id}
required
string <uuid>
{allocation}
required
string <uuid>
{location}
required
string <uuid>
Request Body schema: application/json
required
quantity
required
number

The quantity at this location

note
string or null <= 255 characters

Optional note for the allocation location

Responses

Request samples

Content type
application/json
{
  • "quantity": 20,
  • "note": "Set allocation location"
}

Response samples

Content type
application/json
{
  • "stock": "3ad27da3-adc9-4632-966e-f8e829b4adbd",
  • "location": "string",
  • "quantity": 0,
  • "timestamp": "2019-08-24T14:15:22Z",
  • "tenancy": "acme.org.nz.core",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Delete Allocation Location

Removes a specific location from a stock allocation.

This endpoint validates that the allocation and location belong to the specified stock before making changes.

Required Grants:

  • spoonbill:stockAllocationLocation:override
path Parameters
{id}
required
string <uuid>
{allocation}
required
string <uuid>
{location}
required
string <uuid>

Responses

Response samples

Content type
text/plain
Allocation location not found

Get Location Allocations

Gets all allocations associated with a specific stock location.

This endpoint validates that the location belongs to the specified stock.

Required Grants:

  • spoonbill:stock:get
path Parameters
{id}
required
string <uuid>
{location}
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]