Currency

Currencies are used to keep track of discrete customer balances. A loyalty program can have any number of currencies, and a customer can hold a unique balance in each.

The currency model

The currency model contains identifying information about the currency.

Properties

Name
id
Type
string
Description
Unique identifier for the currency.
Name
code
Type
string or null
Description
ISO-4217 currency code used for identifying cash-like currencies. This value will be null for loyalty currencies.
Name
name
Type
string
Description
A unique name for the currency.
Name
date_created
Type
string
Description
Timestamp of when the currency was first created.
Name
date_updated
Type
string
Description
Timestamp of when the currency was last updated.
Name
status
Type
string
Description
A string enum for indicating the current status of the currency.

GET/currencies

Retrieve a list of currencies

This endpoint allows you to retrieve a paginated list of your currencies. By default, this will include the 25 most recent objects, starting with the most recent.

Query parameters

Name
limit
Type
integer
Description
The maximum number of entries to include in the response.

Name
page
Type
integer
Description
An offset to determine which groups of results to return.

Name
query
Type
string
Description
A search string which can be used to filter results by various criteria (see below).

Filter parameters

These attributes can be used to filter the result set returned by the API. They are included as a space-delimited string of key:value pairs.

Name
n
Type
string
Description
Name of the currency.

Request

GET

/currencies

curl -G https://api.spoonity.com/currencies \
  -H "Authorization: Bearer {token}"

Response

{
  "items": [
    {
        "id": "curr_17b0187c18577b36",
        "code": "USD",
        "name": "American Dollar",
        "date_created": "2026-02-02T13:48:05.683Z",
        "date_updated": "2026-02-02T13:48:05.683Z",
        "status": "ACTIVE",
    },
    {
        "id": "curr_89bb94193b8d576f",
        "code": null,
        "name": "Points",
        "date_created": "2026-02-02T13:48:05.683Z",
        "date_updated": "2026-02-02T13:48:05.683Z",
        "status": "ACTIVE",
    }
  ],
  "next": "https://api.spoonity.com/currencies?limit=25&page=2",
  "prev": null
}

GET/currencies/:id

Retrieve a particular currency

This endpoint allows you to retrieve a specific currency by ID.

Path parameters

Name
id
Type
string
Description
The currency ID.

Request

GET

/currencies/:id

curl -G https://api.spoonity.com/currencies/:id \
-H "Authorization: Bearer {token}"

Response

{
    "id": "curr_17b0187c18577b36",
    "code": "USD",
    "name": "American Dollar",
    "date_created": "2026-02-02T13:48:05.683Z",
    "date_updated": "2026-02-02T13:48:05.683Z",
    "status": "ACTIVE",
}

POST/currencies

Create a currency

This endpoint allows you to add a new currency. A currency requires a name, and will optionally include an ISO-4217 currency code if representing a cash-like currency.

Required attributes

Name
name
Type
string
Description
The name of the currency.

Optional attributes

Name
code
Type
string
Description
An ISO-4217 currency code.

Request

POST

/currencies

curl -G https://api.spoonity.com/currencies \
-H "Authorization: Bearer {token}" \
-d name="Points"

Response

{
    "id": "curr_89bb94193b8d576f",
    "code": null,
    "name": "Points",
    "date_created": "2026-02-02T13:48:05.683Z",
    "date_updated": "2026-02-02T13:48:05.683Z",
    "status": "ACTIVE",
}

PUT/currencies/:id

Update a currency

This endpoint allows you to update a currency. A currency's name, code, and status can be updated.

Path parameters

Name
id
Type
string
Description
The currency ID.

Optional attributes

Name
name
Type
string
Description
The name of the currency.

Name
code
Type
string
Description
An ISO-4217 currency code.

Name
status
Type
string
Description
A status enum. Currencies can exist in either an ACTIVE or ARCHIVED state.

Request

PUT

/currencies/:id

curl -G https://api.spoonity.com/currencies/:id \
--request PUT \
-H "Authorization: Bearer {token}" \
-d name="Points"

Response

{
    "id": "curr_89bb94193b8d576f",
    "code": null,
    "name": "Points",
    "date_created": "2026-02-02T13:48:05.683Z",
    "date_updated": "2026-02-02T13:48:05.683Z",
    "status": "ACTIVE",
}

DELETE/currencies/:id

Delete a currency

This endpoint allows you to delete a currency. Deleted currencies will no longer be accessible.

Path parameters

Name
id
Type
string
Description
The currency ID.

Request

DELETE

/currencies/:id

curl -G https://api.spoonity.com/currencies/:id \
--request DELETE \
-H "Authorization: Bearer {token}"

Response

{}

Currency

Currencies are used to keep track of discrete customer balances. A loyalty program can have any number of currencies, and a customer can hold a unique balance in each.

The currency model

The currency model contains identifying information about the currency.

Properties

Name
id
Type
string
Description
Unique identifier for the currency.
Name
code
Type
string or null
Description
ISO-4217 currency code used for identifying cash-like currencies. This value will be null for loyalty currencies.
Name
name
Type
string
Description
A unique name for the currency.
Name
date_created
Type
string
Description
Timestamp of when the currency was first created.
Name
date_updated
Type
string
Description
Timestamp of when the currency was last updated.
Name
status
Type
string
Description
A string enum for indicating the current status of the currency.

GET/currencies

Retrieve a list of currencies

This endpoint allows you to retrieve a paginated list of your currencies. By default, this will include the 25 most recent objects, starting with the most recent.

Query parameters

Name
limit
Type
integer
Description
The maximum number of entries to include in the response.

Name
page
Type
integer
Description
An offset to determine which groups of results to return.

Name
query
Type
string
Description
A search string which can be used to filter results by various criteria (see below).

Filter parameters

These attributes can be used to filter the result set returned by the API. They are included as a space-delimited string of key:value pairs.

Name
n
Type
string
Description
Name of the currency.

Request

GET

/currencies

curl -G https://api.spoonity.com/currencies \
  -H "Authorization: Bearer {token}"

Response

{
  "items": [
    {
        "id": "curr_17b0187c18577b36",
        "code": "USD",
        "name": "American Dollar",
        "date_created": "2026-02-02T13:48:05.683Z",
        "date_updated": "2026-02-02T13:48:05.683Z",
        "status": "ACTIVE",
    },
    {
        "id": "curr_89bb94193b8d576f",
        "code": null,
        "name": "Points",
        "date_created": "2026-02-02T13:48:05.683Z",
        "date_updated": "2026-02-02T13:48:05.683Z",
        "status": "ACTIVE",
    }
  ],
  "next": "https://api.spoonity.com/currencies?limit=25&page=2",
  "prev": null
}

GET/currencies/:id

Retrieve a particular currency

This endpoint allows you to retrieve a specific currency by ID.

Path parameters

Name
id
Type
string
Description
The currency ID.

Request

GET

/currencies/:id

curl -G https://api.spoonity.com/currencies/:id \
-H "Authorization: Bearer {token}"

Response

{
    "id": "curr_17b0187c18577b36",
    "code": "USD",
    "name": "American Dollar",
    "date_created": "2026-02-02T13:48:05.683Z",
    "date_updated": "2026-02-02T13:48:05.683Z",
    "status": "ACTIVE",
}

POST/currencies

Create a currency

This endpoint allows you to add a new currency. A currency requires a name, and will optionally include an ISO-4217 currency code if representing a cash-like currency.

Required attributes

Name
name
Type
string
Description
The name of the currency.

Optional attributes

Name
code
Type
string
Description
An ISO-4217 currency code.

Request

POST

/currencies

curl -G https://api.spoonity.com/currencies \
-H "Authorization: Bearer {token}" \
-d name="Points"

Response

{
    "id": "curr_89bb94193b8d576f",
    "code": null,
    "name": "Points",
    "date_created": "2026-02-02T13:48:05.683Z",
    "date_updated": "2026-02-02T13:48:05.683Z",
    "status": "ACTIVE",
}

PUT/currencies/:id

Update a currency

This endpoint allows you to update a currency. A currency's name, code, and status can be updated.

Path parameters

Name
id
Type
string
Description
The currency ID.

Optional attributes

Name
name
Type
string
Description
The name of the currency.

Name
code
Type
string
Description
An ISO-4217 currency code.

Name
status
Type
string
Description
A status enum. Currencies can exist in either an ACTIVE or ARCHIVED state.

Request

PUT

/currencies/:id

curl -G https://api.spoonity.com/currencies/:id \
--request PUT \
-H "Authorization: Bearer {token}" \
-d name="Points"

Response

{
    "id": "curr_89bb94193b8d576f",
    "code": null,
    "name": "Points",
    "date_created": "2026-02-02T13:48:05.683Z",
    "date_updated": "2026-02-02T13:48:05.683Z",
    "status": "ACTIVE",
}

DELETE/currencies/:id

Delete a currency

This endpoint allows you to delete a currency. Deleted currencies will no longer be accessible.

Path parameters

Name
id
Type
string
Description
The currency ID.

Request

DELETE

/currencies/:id

curl -G https://api.spoonity.com/currencies/:id \
--request DELETE \
-H "Authorization: Bearer {token}"

Response

{}