Orishare
API reference

List currencies

GET
/currencies

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

limit?integer
Range1 <= value <= 200
Default50
cursor?string
Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/currencies"
{  "data": [    {      "id": "string",      "code": "string",      "name": "string",      "precision": 0,      "expiration_policy": {        "type": "never",        "days": 1      },      "negative_balance": "forbid",      "capabilities": {        "schema": "orishare.currency-capabilities/v1",        "spendable": true,        "transferable": true,        "qualification": "none",        "expiry": {          "type": "none"        }      },      "version": 0,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Create a currency

POST
/currencies

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/currencies" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "code": "points",    "name": "Points"  }'
{  "id": "string",  "code": "string",  "name": "string",  "precision": 0,  "expiration_policy": {    "type": "never",    "days": 1  },  "negative_balance": "forbid",  "capabilities": {    "schema": "orishare.currency-capabilities/v1",    "spendable": true,    "transferable": true,    "qualification": "none",    "expiry": {      "type": "none"    }  },  "version": 0,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

One currency by id or code

GET
/currencies/{id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/currencies/string"
{  "id": "string",  "code": "string",  "name": "string",  "precision": 0,  "expiration_policy": {    "type": "never",    "days": 1  },  "negative_balance": "forbid",  "capabilities": {    "schema": "orishare.currency-capabilities/v1",    "spendable": true,    "transferable": true,    "qualification": "none",    "expiry": {      "type": "none"    }  },  "version": 0,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Rename, change expiration policy or negative-balance policy

PATCH
/currencies/{id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length
If-Match?string

Optional legacy revision. Missing or malformed values follow the existing route parser.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/currencies/string" \  -H "Content-Type: application/json" \  -d '{    "name": "Updated"  }'
{  "id": "string",  "code": "string",  "name": "string",  "precision": 0,  "expiration_policy": {    "type": "never",    "days": 1  },  "negative_balance": "forbid",  "capabilities": {    "schema": "orishare.currency-capabilities/v1",    "spendable": true,    "transferable": true,    "qualification": "none",    "expiry": {      "type": "none"    }  },  "version": 0,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Delete an unused currency (409 when referenced)

DELETE
/currencies/{id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/currencies/string"
Empty

List entries (newest first)

GET
/ledger_entries

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

limit?integer
Range1 <= value <= 200
Default50
cursor?string
Lengthlength <= 2048
customer_id?string
currency?string
type?string

Value in

  • "earn"
  • "spend"
  • "expire"
  • "reverse"
  • "adjust"

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/ledger_entries"
{  "data": [    {      "id": "string",      "customer_id": "string",      "currency": "string",      "type": "earn",      "status": "pending",      "amount": 0,      "remaining": 0,      "confirm_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "reversal_of": "string",      "source_type": "string",      "source_id": "string",      "idempotency_key": "string",      "reason": "string",      "created_at": "2019-08-24T14:15:22Z",      "wallet_command": {        "key": "string",        "amount": -9007199254740991,        "parts": [          {            "entry_id": "string",            "customer_id": "string",            "amount": -9007199254740991          }        ]      }    }  ],  "next_cursor": "string",  "has_more": true}

Manual adjustment (positive credits a lot, negative spends FIFO)

POST
/ledger_entries

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/ledger_entries" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_0123456789abcdef0123456789abcdef",    "currency": "points",    "amount": 10,    "reason": "Manual credit"  }'
{  "id": "string",  "customer_id": "string",  "currency": "string",  "type": "earn",  "status": "pending",  "amount": 0,  "remaining": 0,  "confirm_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "reversal_of": "string",  "source_type": "string",  "source_id": "string",  "idempotency_key": "string",  "reason": "string",  "created_at": "2019-08-24T14:15:22Z",  "wallet_command": {    "key": "string",    "amount": -9007199254740991,    "parts": [      {        "entry_id": "string",        "customer_id": "string",        "amount": -9007199254740991      }    ]  }}

One entry

GET
/ledger_entries/{id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/ledger_entries/string"
{  "id": "string",  "customer_id": "string",  "currency": "string",  "type": "earn",  "status": "pending",  "amount": 0,  "remaining": 0,  "confirm_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "reversal_of": "string",  "source_type": "string",  "source_id": "string",  "idempotency_key": "string",  "reason": "string",  "created_at": "2019-08-24T14:15:22Z",  "wallet_command": {    "key": "string",    "amount": -9007199254740991,    "parts": [      {        "entry_id": "string",        "customer_id": "string",        "amount": -9007199254740991      }    ]  }}

Balances per currency

GET
/customers/{id}/balances

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 200
Default50
cursor?string
Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/string/balances"
{  "data": [    {      "customer_id": "string",      "currency": "string",      "available": 0,      "pending": 0,      "lifetime_earned": 0,      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Revenue from members and non-members, reward cost, liability and ROI for a period, per ISO currency

GET
/loyalty/roi

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

from?string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
Formatdate-time
to?string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
Formatdate-time
currency?string
Match^[A-Za-z]{3}$

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/loyalty/roi"
{  "period": {    "from": "2019-08-24T14:15:22Z",    "to": "2019-08-24T14:15:22Z",    "days": 0  },  "currency": "string",  "order_events": [    "string"  ],  "coverage": {    "order_facts_retained_from": "2019-08-24T14:15:22Z",    "complete": true,    "skipped_orders": 0  },  "revenue": [    {      "iso_currency": "string",      "orders": 0,      "revenue_minor": 0,      "members": {        "orders": 0,        "revenue_minor": 0,        "average_order_value_minor": 0      },      "non_members": {        "orders": 0,        "revenue_minor": 0,        "average_order_value_minor": 0      },      "influenced": {        "orders": 0,        "revenue_minor": 0      }    }  ],  "repeat_purchase": {    "all": {      "customers": 0,      "repeat_customers": 0,      "rate": 0    },    "members": {      "customers": 0,      "repeat_customers": 0,      "rate": 0    },    "non_members": {      "customers": 0,      "repeat_customers": 0,      "rate": 0    }  },  "reward_cost": [    {      "iso_currency": "string",      "store_credit_captured_minor": 0,      "store_credit_refunded_minor": 0,      "partner_rewards_merchant_minor": 0,      "points_redeemed_value_minor": 0,      "total_minor": 0,      "partner_funded_minor": 0    }  ],  "points": [    {      "currency": "string",      "currency_id": "string",      "store_credit": true,      "issued": 0,      "redeemed": 0,      "expired": 0,      "transferred": 0,      "outstanding": 0,      "pending": 0,      "valuation": {        "iso_currency": "string",        "minor_per_unit": "string",        "outstanding_value_minor": 0,        "redeemed_value_minor": 0      }    }  ],  "store_credit_liability": [    {      "currency": "string",      "iso_currency": "string",      "minor_unit": 0,      "outstanding_minor": 0    }  ],  "roi": [    {      "iso_currency": "string",      "incremental_revenue_minor": 0,      "reward_cost_minor": 0,      "roi": 0,      "reason": "no_member_orders"    }  ],  "method": "string",  "limitations": [    "string"  ]}

Which events are orders, and what a point is worth, for the ROI report

GET
/loyalty/reporting_settings

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/loyalty/reporting_settings"
{  "order_events": [    "string"  ],  "point_values": [    {      "currency_id": "string",      "currency": "string",      "iso_currency": "string",      "minor_per_unit": "string"    }  ],  "configured": true,  "version": 0,  "updated_at": "2019-08-24T14:15:22Z"}

Set the order events and point values the ROI report uses

POST
/loyalty/reporting_settings

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/loyalty/reporting_settings" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "order_events": [      "order.completed"    ],    "point_values": [      {        "currency": "points",        "iso_currency": "USD",        "minor_per_unit": "0.5"      }    ]  }'
{  "order_events": [    "string"  ],  "point_values": [    {      "currency_id": "string",      "currency": "string",      "iso_currency": "string",      "minor_per_unit": "string"    }  ],  "configured": true,  "version": 0,  "updated_at": "2019-08-24T14:15:22Z"}

Transfers a customer sent or received (newest first)

GET
/customers/{id}/transfers

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 200
Default50
cursor?string
Lengthlength <= 2048
currency?string
Length1 <= length <= 64

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/string/transfers"
{  "data": [    {      "id": "string",      "initiated_by": "operator",      "sender_customer_id": "string",      "receiver_customer_id": "string",      "currency": "string",      "currency_id": "string",      "amount": 0,      "note": "string",      "debit_entry_id": "string",      "credit_entry_id": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Transfer points from this customer to another customer

POST
/customers/{id}/transfers

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customers/string/transfers" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "recipient": {      "external_id": "friend-42"    },    "currency": "points",    "amount": 250,    "note": "Gift to a friend"  }'
{  "id": "string",  "initiated_by": "operator",  "sender_customer_id": "string",  "receiver_customer_id": "string",  "currency": "string",  "currency_id": "string",  "amount": 0,  "note": "string",  "debit_entry_id": "string",  "credit_entry_id": "string",  "created_at": "2019-08-24T14:15:22Z"}

One points transfer

GET
/points_transfers/{id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/points_transfers/string"
{  "id": "string",  "initiated_by": "operator",  "sender_customer_id": "string",  "receiver_customer_id": "string",  "currency": "string",  "currency_id": "string",  "amount": 0,  "note": "string",  "debit_entry_id": "string",  "credit_entry_id": "string",  "created_at": "2019-08-24T14:15:22Z"}

Transfer limits of a currency, and whether customers may transfer it

GET
/currencies/{id}/transfer_limits

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/currencies/string/transfer_limits"
{  "currency_id": "string",  "currency": "string",  "transferable": true,  "min_amount": 0,  "max_amount": 0,  "daily_max": 0,  "customer_enabled": true,  "configured": true,  "version": 0,  "updated_at": "2019-08-24T14:15:22Z"}

Set the transfer limits of a currency (omitted fields keep their value)

POST
/currencies/{id}/transfer_limits

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/currencies/string/transfer_limits" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "min_amount": 100,    "max_amount": 5000,    "daily_max": 10000,    "customer_enabled": true  }'
{  "currency_id": "string",  "currency": "string",  "transferable": true,  "min_amount": 0,  "max_amount": 0,  "daily_max": 0,  "customer_enabled": true,  "configured": true,  "version": 0,  "updated_at": "2019-08-24T14:15:22Z"}

Leagues

Weekly cohorts on a tier ladder with promotion, demotion and rank rewards.

Levels

Native XP qualification, levels and prestige.