Promotional Codes API — Discounts and User Types

Create and manage promotional discount codes. Apply codes to charging sessions, track usage, and manage driver user types for targeted pricing.

The promotional codes API lets you create discount codes that drivers can apply to their charging sessions. Codes support both percentage-based and fixed-amount discounts, with optional usage limits and expiry dates. This section also covers the user types API, which lets you segment drivers into groups for use with billing rules.

Create a promotional code

POST /api/v1/billing/promotional-codes

code · string · required

The code string drivers will enter (e.g. SUMMER25). Must be unique within your organisation. Uppercase letters and numbers only, 4–20 characters.

discount_type · string · required

How the discount is calculated. Accepted values: percent (percentage off the total), fixed (fixed amount off the total).

discount_value · number · required

The discount amount. For percent, this is the percentage (e.g. 25 for 25% off). For fixed, this is the amount in your default currency.

currency · string

ISO 4217 currency code. Required when discount_type is fixed.

max_uses · number

Maximum number of times this code can be redeemed across all users. Leave unset for unlimited uses.

max_uses_per_user · number

Maximum number of times a single user can redeem this code. Leave unset for unlimited.

expires_at · string

ISO 8601 date/time after which the code can no longer be applied. Leave unset for no expiry.

description · string

Internal description for the code — not shown to drivers.

curl -X POST "https://api.dynamo-csms.com/api/v1/billing/promotional-codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER25",
    "discount_type": "percent",
    "discount_value": 25,
    "max_uses": 500,
    "max_uses_per_user": 1,
    "expires_at": "2024-08-31T23:59:59Z",
    "description": "Summer 2024 promotion — 25% off one session"
  }'

{
  "code_id": "promo_7XNBQ",
  "code": "SUMMER25",
  "discount_type": "percent",
  "discount_value": 25,
  "currency": null,
  "max_uses": 500,
  "max_uses_per_user": 1,
  "uses_count": 0,
  "expires_at": "2024-08-31T23:59:59Z",
  "description": "Summer 2024 promotion — 25% off one session",
  "active": true,
  "created_at": "2024-06-01T10:00:00Z"
}

code_id · string

Unique identifier for the promotional code.

code · string

The code string.

uses_count · number

Number of times this code has been successfully redeemed.

active · boolean

Whether the code is currently redeemable. Set to false automatically when max_uses is reached or expires_at passes.

---

List promotional codes

GET /api/v1/billing/promotional-codes

Returns all promotional codes in your organisation.

active · boolean

Filter by active status.

discount_type · string

Filter by discount type: percent or fixed.

limit · number · default: "50"

Maximum number of codes to return.

offset · number · default: "0"

Pagination offset.

curl "https://api.dynamo-csms.com/api/v1/billing/promotional-codes?active=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "codes": [
    {
      "code_id": "promo_7XNBQ",
      "code": "SUMMER25",
      "discount_type": "percent",
      "discount_value": 25,
      "uses_count": 47,
      "max_uses": 500,
      "expires_at": "2024-08-31T23:59:59Z",
      "active": true
    }
  ],
  "total": 1
}

---

Get a promotional code

GET /api/v1/billing/promotional-codes/{code_id}

code_id · string · required

The unique identifier of the promotional code.

curl "https://api.dynamo-csms.com/api/v1/billing/promotional-codes/promo_7XNBQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "code_id": "promo_7XNBQ",
  "code": "SUMMER25",
  "discount_type": "percent",
  "discount_value": 25,
  "currency": null,
  "max_uses": 500,
  "max_uses_per_user": 1,
  "uses_count": 47,
  "expires_at": "2024-08-31T23:59:59Z",
  "description": "Summer 2024 promotion — 25% off one session",
  "active": true,
  "created_at": "2024-06-01T10:00:00Z"
}

---

Apply a promotional code to a session

POST /api/v1/billing/promotional-codes/sessions/{session_id}/apply-code

Applies a promotional code to a completed session. The discount is calculated and recorded against the session. This endpoint can be called by a driver application or by an operator on behalf of a driver.

Codes can only be applied to sessions with status completed. Active sessions cannot have a code applied until the session ends.

session_id · string · required

The billing session to apply the code to.

code · string · required

The promotional code string to apply.

curl -X POST "https://api.dynamo-csms.com/api/v1/billing/promotional-codes/sessions/sess_7MNBPX/apply-code" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "SUMMER25"}'

{
  "session_id": "sess_7MNBPX",
  "code": "SUMMER25",
  "code_id": "promo_7XNBQ",
  "discount_type": "percent",
  "discount_value": 25,
  "original_cost": 5.52,
  "discount_amount": 1.38,
  "final_cost": 4.14,
  "currency": "GBP",
  "applied_at": "2024-06-05T09:45:00Z"
}

original_cost · number

Session total before the code was applied.

discount_amount · number

Amount discounted from the session.

final_cost · number

Session total after the discount.

---

Get promotional code usage stats

GET /api/v1/billing/promotional-codes/{code_id}/usage

Returns detailed usage statistics for a promotional code, including a breakdown of redemptions over time.

code_id · string · required

The unique identifier of the promotional code.

from · string

ISO 8601 start date/time to filter usage from.

to · string

ISO 8601 end date/time to filter usage to.

curl "https://api.dynamo-csms.com/api/v1/billing/promotional-codes/promo_7XNBQ/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "code_id": "promo_7XNBQ",
  "code": "SUMMER25",
  "total_redemptions": 47,
  "unique_users": 47,
  "total_discount_given": 64.86,
  "currency": "GBP",
  "redemptions_by_day": [
    { "date": "2024-06-01", "count": 5, "discount_total": 6.90 },
    { "date": "2024-06-02", "count": 8, "discount_total": 11.04 },
    { "date": "2024-06-03", "count": 12, "discount_total": 16.56 }
  ]
}

total_redemptions · number

Total number of times the code has been applied.

unique_users · number

Number of distinct users who redeemed the code.

total_discount_given · number

Total value discounted across all redemptions.

redemptions_by_day · object[]

Daily redemption counts and discount totals for the requested period.

---

User types

User types let you segment drivers into groups so billing rules can target them specifically. For example, you might create types like staff, fleet, and public and then write rules that grant free sessions to staff drivers.

Create a user type

POST /api/v1/billing/user-types

name · string · required

Unique name for the user type (e.g. staff, fleet-customer, vip).

description · string

Optional description of who belongs to this type.

curl -X POST "https://api.dynamo-csms.com/api/v1/billing/user-types" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staff",
    "description": "Company employees eligible for free charging"
  }'

{
  "user_type_id": "utype_3KLMX",
  "name": "staff",
  "description": "Company employees eligible for free charging",
  "created_at": "2024-06-01T09:00:00Z"
}

---

List user types

GET /api/v1/billing/user-types

Returns all user types in your organisation.

curl "https://api.dynamo-csms.com/api/v1/billing/user-types" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "user_types": [
    {
      "user_type_id": "utype_3KLMX",
      "name": "staff",
      "description": "Company employees eligible for free charging",
      "user_count": 18,
      "created_at": "2024-06-01T09:00:00Z"
    },
    {
      "user_type_id": "utype_9XVBQ",
      "name": "fleet",
      "description": "Fleet account drivers",
      "user_count": 64,
      "created_at": "2024-05-15T10:30:00Z"
    }
  ]
}

---

Assign a user type to a driver

PUT /api/v1/billing/user-types/users/{user_id}/user-type

Sets the user type for a specific driver. Replaces any previously assigned type.

user_id · string · required

The user to assign the type to.

user_type_id · string · required

The user type to assign.

curl -X PUT "https://api.dynamo-csms.com/api/v1/billing/user-types/users/usr_9PLKJ/user-type" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_type_id": "utype_3KLMX"}'

{
  "user_id": "usr_9PLKJ",
  "user_type_id": "utype_3KLMX",
  "user_type_name": "staff",
  "assigned_at": "2024-06-15T11:00:00Z"
}