API docs by Redocly

Urban Sharing - Rider API (1.0.0)

Download OpenAPI specification:

Urban Sharing Support: info@urbansharing.com URL: https://www.urbansharing.com

The Rider API provides mobile application access to Urban Sharing mobility services. The API enables rider-facing functionality including trip management, vehicle discovery, reservations, and real-time notifications.

Release History
DateVersionNotes
Wed Feb 11 20261.0.0Initial release

Users

Get User Properties

Returns deletion-related properties for the user.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "markedForDeletionAt": "2026-04-30T10:00:00.000Z",
  • "superpowers": true,
  • "preferredLocale": "en"
}

Mark User For Deletion

Creates a user deletion request for the authenticated user if none exists.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "markedForDeletionAt": "2026-04-30T10:00:00.000Z",
  • "superpowers": true,
  • "preferredLocale": "en"
}

Get User Trips

Returns all historical and current trips of a user

path Parameters
systemId
required
string
query Parameters
states
Array of strings
Items Enum: "starting" "in_progress" "on_hold" "completed" "cancelled"

Example: states[]=completed&states[]=cancelled The trip states to filter by

from
required
string

The start date to filter trips from

to
string

The end date to filter trips until

Responses

Response samples

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

Get User Reservations

Returns all active vehicle reservations for the user (excludes completed and cancelled)

path Parameters
systemId
required
string

Responses

Response samples

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

Get User Statistics

Returns aggregated statistics for a user including distance, trips, CO2 saved, calories burned, and spending.

path Parameters
systemId
required
string
query Parameters
from
required
string

The start date to filter from

to
string

The end date to filter until

Responses

Response samples

Content type
application/json
{
  • "totalTrips": 42,
  • "totalDistanceKm": 123.45,
  • "totalRidingTimeSec": 3600,
  • "co2SavedGrams": 14814,
  • "caloriesBurned": 3703,
  • "totalSpentCents": 5000,
  • "currency": "NOK"
}

Get User Subscription

Returns the current active subscription for the user, or 404 if no active subscription exists.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "enabled": true,
  • "validFrom": "2024-01-01T00:00:00.000Z",
  • "validTo": "2024-12-31T23:59:59.999Z",
  • "product": {
    },
  • "isCancellable": true,
  • "autoRenewal": false
}

Cancel User Subscription

Cancels the current active subscription for the user. Only subscriptions for free products or products marked as publicly cancellable can be cancelled.

path Parameters
systemId
required
string

Responses

Update Subscription Auto-Renewal

Enables or disables auto-renewal for the current active subscription.

path Parameters
systemId
required
string
Request Body schema: application/json
required
isEnabled
required
boolean

Whether auto-renew should be enabled for the current subscription

Responses

Request samples

Content type
application/json
{
  • "isEnabled": true
}

Response samples

Content type
application/json
{
  • "id": 123,
  • "enabled": true,
  • "validFrom": "2024-01-01T00:00:00.000Z",
  • "validTo": "2024-12-31T23:59:59.999Z",
  • "product": {
    },
  • "isCancellable": true,
  • "autoRenewal": false
}

Cancel User Deletion Request

Cancels any active deletion request for the authenticated user.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "markedForDeletionAt": "2026-04-30T10:00:00.000Z",
  • "superpowers": true,
  • "preferredLocale": "en"
}

Update User Preferred Locale

Updates the preferred locale for the authenticated user.

path Parameters
systemId
required
string
Request Body schema: application/json
required
preferredLocale
required
string

The preferred locale of the user

Responses

Request samples

Content type
application/json
{
  • "preferredLocale": "en"
}

Response samples

Content type
application/json
{
  • "preferredLocale": "en"
}

Refer a Friend

Send a referral invitation to a friend via email.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{}

Onboarding

Get User Onboarding State

Returns the current onboarding state of the user.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Name

Submit the first and last name for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
firstName
required
string

First name

lastName
required
string

Last name

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Gender

Submit the gender for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
gender
required
string
Enum: "male" "female" "other"

Gender

Responses

Request samples

Content type
application/json
{
  • "gender": "male"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Phone Number

Submit the phone number for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
phoneNumber
required
string

The phone number

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "+4712345678"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Email

Submit the email address for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
email
required
string

The email address

emailMarketingConsent
required
boolean

Whether the user consents to email marketing

emailNewsConsent
required
boolean

Whether the user consents to email newsletters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "emailMarketingConsent": true,
  • "emailNewsConsent": true
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Birthdate

Submit the birthdate for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
birthdate
required
string <date>

Birthdate as an ISO 8601 date string

Responses

Request samples

Content type
application/json
{
  • "birthdate": "1990-05-20"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Street Address

Submit the street address for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
streetAddress
required
string

Street address line

streetAddress2
string

Second address line

streetAddress3
string

Third address line

postalCode
required
string

Postal code

city
required
string

City

countryCode
string

Country code (ISO 3166-1 alpha-2)

Responses

Request samples

Content type
application/json
{
  • "streetAddress": "Storgata 1",
  • "streetAddress2": "Apt 2",
  • "streetAddress3": "Building C",
  • "postalCode": "0182",
  • "city": "Oslo",
  • "countryCode": "NO"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Personal Number

Submit the personal identification number for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
personalNumber
required
string

The personal identification number (national ID)

Responses

Request samples

Content type
application/json
{
  • "personalNumber": "12345678901"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Accept Privacy Policy

Accept the privacy policy and submit any additional legal consent checkboxes.

path Parameters
systemId
required
string
Request Body schema: application/json
required
accepted
required
boolean

Whether the user accepted the privacy policy

version
string

Version of the privacy policy accepted

Array of objects (LegalConsent)

Additional legal consent checkboxes

Array
key
required
string

Identifier for the legal consent checkbox

accepted
required
boolean

Whether the user accepted this consent

Responses

Request samples

Content type
application/json
{
  • "accepted": true,
  • "version": "2026-03-01",
  • "legalConsents": [
    ]
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Accept Terms and Conditions

Accept the terms and conditions.

path Parameters
systemId
required
string
Request Body schema: application/json
required
accepted
required
boolean

Whether the user accepted the terms and conditions

version
string

Version of the terms and conditions accepted

Responses

Request samples

Content type
application/json
{
  • "accepted": true,
  • "version": "2026-03-01"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Acknowledge Tutorial

Mark the tutorial as acknowledged.

path Parameters
systemId
required
string
Request Body schema: application/json
required
acknowledged
required
boolean

Whether the user acknowledged the tutorial

Responses

Request samples

Content type
application/json
{
  • "acknowledged": true
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Start Verify Phone Number

Start verification of the phone number. Returns a verification state, TTL, and code length.

path Parameters
systemId
required
string
Request Body schema: application/json
required
phoneNumber
required
string

The phone number

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "+4712345678"
}

Response samples

Content type
application/json
{
  • "state": "string",
  • "ttl": 0,
  • "length": 0
}

Verify Phone Number

Complete verification of the phone number by submitting the verification code.

path Parameters
systemId
required
string
Request Body schema: application/json
required
state
required
string

Verification state

code
required
string

The verification code

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Start Verify Email

Start verification of the email address. Returns a verification state, TTL, and code length.

path Parameters
systemId
required
string
Request Body schema: application/json
required
email
required
string

The email address

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "state": "string",
  • "ttl": 0,
  • "length": 0
}

Verify Email

Complete verification of the email address by submitting the verification code.

path Parameters
systemId
required
string
Request Body schema: application/json
required
state
required
string

Verification state

code
required
string

The verification code

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Verify Street Address

Trigger verification of the street address.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Verify Personal Number

Trigger verification of the personal identification number.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Get Legal Entity

Returns the full tax number, name, and postal address for a given legal entity number.

path Parameters
systemId
required
string
legalEntityNumber
required
string

Responses

Response samples

Content type
application/json
{
  • "taxNumber": "11961552-2-42",
  • "name": "Acme Corporation",
  • "address": {
    }
}

Update Legal Entity Number

Submit the legal entity number for the onboarding step.

path Parameters
systemId
required
string
Request Body schema: application/json
required
legalEntityNumber
required
string or null

The legal entity number

Responses

Request samples

Content type
application/json
{
  • "legalEntityNumber": "123456789"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Areas

Get Areas

Get all areas with their configurations and schedules.

path Parameters
systemId
required
string
query Parameters
types
Array of strings
Items Enum: "illegal_docking" "speed_limit" "no_entry"

Example: types[]=illegal_docking&types[]=speed_limit The area configuration types to filter by

Responses

Response samples

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

CRM

Get CRM Settings

Returns CRM configuration for the authenticated user including provider type, app ID, and computed user hash for identity verification.

path Parameters
systemId
required
string
header Parameters
user-agent
required
string

Responses

Response samples

Content type
application/json
{
  • "provider": "intercom",
  • "appId": "abc123xyz",
  • "token": "a1b2c3d4e5f6..."
}

Dock groups

Get Dock Groups

Return all dock groups with availability information.

path Parameters
systemId
required
string
query Parameters
superpowers
boolean

Whether this request is on behalf of a user with superpowers, which may return more information than for a general public user

Responses

Response samples

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

Get Vehicle by Dock Group ID

Returns vehicle data based on the the Dock Group ID.

path Parameters
systemId
required
string
dockGroupId
required
number

Responses

Response samples

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

Get Dock Group

Return one dock group with availability information, if it matches the same visibility rules as the list endpoint.

path Parameters
systemId
required
string
dockGroupId
required
number
query Parameters
superpowers
boolean

Whether this request is on behalf of a user with superpowers, which may return more information than for a general public user

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "type": "virtual",
  • "state": "active",
  • "name": "58",
  • "title": "Railway Station North",
  • "subtitle": "Next to the big clock tower",
  • "address": "123 Railway St, Cityville",
  • "availabilityInfo": {
    },
  • "geometry": {
    }
}

Start Dock Group Trip

Starts a dock group trip.

path Parameters
systemId
required
string
dockGroupId
required
number
Request Body schema: application/json
required
object

User position

required
object

GeoJson Position

type
required
string

GeoJSON type

coordinates
required
Array of strings

Coordinates in the form of [longitude, latitude]

accuracyRadiusMeters
number

The accuracy in meters of the user position

vehicleCategory
required
string
Enum: "bike" "ebike" "scooter" "ebike_with_childseat" "bike_with_childseat" "ebike_cargo" "bike_cargo"

The type of vehicle required for the trip.

Responses

Request samples

Content type
application/json
{
  • "userPosition": {
    },
  • "vehicleCategory": "bike"
}

Response samples

Content type
application/json
{
  • "type": "MAAS_TRIP_STATE_UPDATE",
  • "id": 12345,
  • "clientId": "Client12345",
  • "userId": "User12345",
  • "state": "cancelled",
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string",
  • "startedAtLocation": {
    },
  • "vehicle": {
    },
  • "endedAtLocation": {
    },
  • "totalDistance": 12.55,
  • "updatedAt": "string",
  • "pricing": {
    }
}

Vehicles

Get Vehicles

Return all vehicles with detailed information.

path Parameters
systemId
required
string

Responses

Response samples

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

Get Vehicle by QR code

Returns vehicle data based on its QR code.

path Parameters
systemId
required
string
qrCode
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "model": {
    },
  • "status": "available",
  • "state": "docked",
  • "unavailabilityReasons": [
    ],
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "location": {
    },
  • "qrCode": "string",
  • "isReserved": true,
  • "trip": {
    }
}

Get Vehicle by ID

Returns vehicle data based on the its ID.

path Parameters
systemId
required
string
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "model": {
    },
  • "status": "available",
  • "state": "docked",
  • "unavailabilityReasons": [
    ],
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "location": {
    },
  • "qrCode": "string",
  • "isReserved": true,
  • "trip": {
    }
}

Start Vehicle Trip

Starts a vehicle trip.

path Parameters
systemId
required
string
vehicleId
required
number
Request Body schema: application/json
required
object

User position

required
object

GeoJson Position

type
required
string

GeoJSON type

coordinates
required
Array of strings

Coordinates in the form of [longitude, latitude]

accuracyRadiusMeters
number

The accuracy in meters of the user position

Responses

Request samples

Content type
application/json
{
  • "userPosition": {
    }
}

Response samples

Content type
application/json
{
  • "type": "MAAS_TRIP_STATE_UPDATE",
  • "id": 12345,
  • "clientId": "Client12345",
  • "userId": "User12345",
  • "state": "cancelled",
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string",
  • "startedAtLocation": {
    },
  • "vehicle": {
    },
  • "endedAtLocation": {
    },
  • "totalDistance": 12.55,
  • "updatedAt": "string",
  • "pricing": {
    }
}

Reserve a vehicle

Reserves a specific vehicle

path Parameters
systemId
required
string
vehicleId
required
number
Request Body schema: application/json
required
productId
number

The optional ID of the product being used for the reservation. If the product ID is valid, product validations will be performed before starting the reservation. e.g. valid product, penalty points etc. At the end of the reservation/trip, the product ID will be used to calculate the price and a summary will be sent to the users/invoices webhook. If no product ID is provided, it is the responsibility of the caller to manage pricing and penalties.

Responses

Request samples

Content type
application/json
{
  • "productId": 1
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "vehicleId": 2,
  • "dockGroupId": 2,
  • "userId": "435432",
  • "clientId": "Client12345",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "expiresAt": "string",
  • "completedAt": "string",
  • "cancelledAt": "string"
}

Get Damage Types

Gets the damage types for a vehicle.

path Parameters
systemId
required
string
vehicleId
required
number
query Parameters
locale
required
string

Responses

Response samples

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

Create Damage Report

Creates a damage report for a vehicle.

path Parameters
systemId
required
string
vehicleId
required
number
Request Body schema: application/json
required
damageTypeIds
required
Array of numbers

List of IDs that correspond to the damage types being reported

comment
string

An optional comment related to the damage

notifyOnRepair
boolean

Whether to notify the user when the vehicle has been repaired

tripId
number

The ID of the trip that the damage report is associated with

Responses

Request samples

Content type
application/json
{
  • "damageTypeIds": [
    ],
  • "comment": "The rear wheel is broken",
  • "notifyOnRepair": true,
  • "tripId": 1
}

Response samples

Content type
application/json
{
  • "code": "ERR_INVALID_DAMAGE_REPORT",
  • "message": "Invalid damage report data provided"
}

Uploads

Upload Damage Report Image

Uploads a damage image for a specific trip and damage type. Call after creating the damage report.

Authorizations:
bearer
path Parameters
systemId
required
string
Request Body schema: multipart/form-data
required
tripId
required
number

The ID of the trip the damage report is associated with

assetDamageTypeId
required
number

The asset damage type this image belongs to

image
required
string <binary>

Photo of the damage

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

Upload End-of-Trip Image

Uploads an image associated with a completed or ending trip (e.g. parking verification).

Authorizations:
bearer
path Parameters
systemId
required
string
Request Body schema: multipart/form-data
required
tripId
required
number

The ID of the trip the image is associated with

imageType
required
string

The type of end-of-trip image

image
required
string <binary>

Photo taken at the end of the trip

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

Trips

Get Trip

Returns a trip based on ID

path Parameters
systemId
required
string
tripId
required
number

Responses

Response samples

Content type
application/json
{
  • "type": "MAAS_TRIP_STATE_UPDATE",
  • "id": 12345,
  • "clientId": "Client12345",
  • "userId": "User12345",
  • "state": "cancelled",
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string",
  • "startedAtLocation": {
    },
  • "vehicle": {
    },
  • "endedAtLocation": {
    },
  • "totalDistance": 12.55,
  • "updatedAt": "string",
  • "pricing": {
    }
}

Update Trip

Updates a trip.

path Parameters
systemId
required
string
tripId
required
number
Request Body schema: application/json
required
update
required
string
Enum: "pause" "resume" "cancel" "end"

Set a new trip state. Note that not all states are supported by all vehicle types.

object

User position

required
object

GeoJson Position

type
required
string

GeoJSON type

coordinates
required
Array of strings

Coordinates in the form of [longitude, latitude]

accuracyRadiusMeters
number

The accuracy in meters of the user position

stateTransitionReason
string
Enum: "cancelled_by_administrator" "time_limit_exceeded" "vehicle_communication_timeout" "station_communication_timeout" "user_interaction_timeout" "vehicle_taken_by_administrator" "vehicle_moved_to_operation_location" "vehicle_decommissioned" "illegal_parking"

The reason why the state transistioned to the current state.

stateTransitionComment
string

Text describing the reason why the transition occurred

Responses

Request samples

Content type
application/json
{
  • "update": "end",
  • "userPosition": {
    },
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string"
}

Response samples

Content type
application/json
{
  • "code": "invalid_location",
  • "message": "An error occured"
}

Products

Get Products

Returns all products available

path Parameters
systemId
required
string

Responses

Response samples

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

Reservations

Get a vehicle reservation

Returns a reservation based on the id

path Parameters
systemId
required
string
reservationId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 2,
  • "vehicleId": 2,
  • "dockGroupId": 2,
  • "userId": "435432",
  • "clientId": "Client12345",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "expiresAt": "string",
  • "completedAt": "string",
  • "cancelledAt": "string"
}

Cancel a vehicle reservation

Cancels an existing vehicle reservation

path Parameters
systemId
required
string
reservationId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 2,
  • "vehicleId": 2,
  • "dockGroupId": 2,
  • "userId": "435432",
  • "clientId": "Client12345",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "expiresAt": "string",
  • "completedAt": "string",
  • "cancelledAt": "string"
}

System

Get System

Return a specific system and its relevant information based on the system ID.

path Parameters
systemId
required
string
query Parameters
superpowers
boolean

Whether this request is on behalf of a user with superpowers, which may return more information than for a general public user

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get System Alerts

Return alerts for the system.

path Parameters
systemId
required
string

Responses

Response samples

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

Get all available systems

Returns all systems available for your organization. Optionally filter by position to only return systems whose geometry contains the given coordinates.

path Parameters
systemId
required
string
query Parameters
position
string
Example: position=59.9139,10.7522

Filter systems by position. Format: "lat,lng" (e.g., "59.9139,10.7522"). Only returns systems whose geometry contains this position.

Responses

Response samples

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

Payments

Create Subscription Order

Creates a subscription order for the specified product.

path Parameters
systemId
required
string
header Parameters
locale
required
string
Request Body schema: application/json
required
productId
required
string

Product ID to create subscription for

enableAutoRenew
boolean

Enable auto-renewal for this subscription order

Responses

Request samples

Content type
application/json
{
  • "productId": "string",
  • "enableAutoRenew": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Create Wallet Deposit Order

Creates an order to deposit funds into the user wallet.

path Parameters
systemId
required
string
header Parameters
locale
required
string
Request Body schema: application/json
required
amount
number

Amount to deposit into wallet

Responses

Request samples

Content type
application/json
{
  • "amount": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Create Voucher Code Order

Creates an order for voucher/gift codes.

path Parameters
systemId
required
string
header Parameters
locale
required
string
Request Body schema: application/json
required
customerEmail
required
string

Customer email address

required
Array of objects (OrderLineInputDto)

Order lines with product and quantity

Array
productId
required
string

Product ID

quantity
required
number >= 1

Quantity

receiptEmail
string

Email to send receipt to

Responses

Request samples

Content type
application/json
{
  • "customerEmail": "string",
  • "orderLines": [
    ],
  • "receiptEmail": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

List Orders

Returns a paginated list of user orders.

path Parameters
systemId
required
string
query Parameters
statuses
Array of strings
Items Enum: "pending" "completed" "cancelled" "failed"

Filter by order statuses

limit
number
Default: 20

Maximum number of results to return

offset
number
Default: 0

Number of results to skip

orderBy
string
Enum: "createdAt" "completedAt"

Field to sort by

orderDirection
string
Enum: "asc" "desc"

Sort direction

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "paginationInfo": {
    }
}

Get Order

Returns a single order by its token.

path Parameters
systemId
required
string
token
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Apply Discount Code

Applies a discount code to an existing unpaid order.

path Parameters
systemId
required
string
orderId
required
string
Request Body schema: application/json
required
code
required
string

Discount code to apply

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Remove Discount Code

Removes the applied discount code from an order.

path Parameters
systemId
required
string
orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Pay

Initiates payment for an order or invoice.

path Parameters
systemId
required
string
header Parameters
locale
required
string
Request Body schema: application/json
required
documentId
required
string

Document ID (order or invoice ID)

documentType
required
string
Enum: "order" "invoice"

Document type

required
object

Payment parameters

selectedPaymentMethod
required
string
Enum: "card" "wallet" "blik" "any"

Payment method to use

enableAutoRenew
boolean

Enable auto-renewal for subscriptions

save
boolean

Save payment method for future use

Responses

Request samples

Content type
application/json
{
  • "documentId": "string",
  • "documentType": "order",
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "publishableKey": "string",
  • "clientSecret": "string",
  • "customerRef": "string",
  • "customerKey": "string",
  • "webUrl": "string",
  • "paymentMethodRef": "string",
  • "orderToken": "string",
  • "state": "CREATED",
  • "errorCode": "string",
  • "message": "string",
  • "description": "string"
}

Get Payment Methods

Returns the current payment methods for the user.

path Parameters
systemId
required
string

Responses

Response samples

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

Add Payment Method

Initiates the flow to add a new payment method.

path Parameters
systemId
required
string
header Parameters
locale
required
string
Request Body schema: application/json
required
object

Redirect paths

successPath
required
string

URL to redirect to on success

cancelPath
required
string

URL to redirect to on cancel

Responses

Request samples

Content type
application/json
{
  • "paths": {
    }
}

Response samples

Content type
application/json
{
  • "webUrl": "string",
  • "provider": "stripe",
  • "url": "string",
  • "setupToken": "string",
  • "sessionId": "string",
  • "publishableKey": "string",
  • "clientSecret": "string"
}

Replace Payment Method

Initiates the flow to replace the existing payment method.

path Parameters
systemId
required
string
header Parameters
locale
required
string
Request Body schema: application/json
required
object

Redirect paths

successPath
required
string

URL to redirect to on success

cancelPath
required
string

URL to redirect to on cancel

Responses

Request samples

Content type
application/json
{
  • "paths": {
    }
}

Response samples

Content type
application/json
{
  • "webUrl": "string",
  • "provider": "stripe",
  • "url": "string",
  • "setupToken": "string",
  • "sessionId": "string",
  • "publishableKey": "string",
  • "clientSecret": "string"
}

Remove Payment Method

Removes the user payment method.

path Parameters
systemId
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "ERR_PAYMENT_ERROR",
  • "message": "Payment processing failed"
}