List partner orders
This endpoint is used to retrieve data on all orders you have access to, a filtered list of orders, or just a single order.
Returned orders are always filtered initially for the partner based on the API key in use. All parameters are optional. In the absence of any filter parameters, it will return all orders that this API key has access to.
The response format can be controlled using the 'compact' parameter. When compact=true, a minimal set of order attributes is returned. When compact=false or not specified, detailed order information is returned.
Request
- Base URL: http://localhost:5100
- URL: http://localhost:5100/api/v2/partner/orders
- Auth: API key in header Authorization
Query parameters
Specify the email address to identify the user of interest. If a user has orders with organisations across multiple partners, the result is still filtered by partner of the API key in use
Specify a user ID to identify the user of interest. If a user has orders with organisations across multiple partners, the result is still filtered by partner of the API key in use
An alternative to email, as a way of filtering orders by a particular user of interest.
The partner_user_identifier is a field in the vivup database holding a unique user identifier supplied by the partner (Currently this only happens during SSO user creations by passing a ParterUserIdentifier SAML attribute)
Specify the partner's client id, identifying a particular organisation. If a client_id is specified which does not belong to any organisation, then no order will be returned but the request will be successful. If client_id is not provided in the request then all the orders of the partner's organisations will be returned
Partner User Identifier of the actor performing the action
Specify a benefit type to filter orders by e.g. home_and_electronics, cycle_to_work, family_care.
When true, returns a compact version of order data with minimal attributes. When false or not specified, returns detailed order information.
Size of the page
Filter by multiple first names
Filter by multiple last names
Filter by multiple employee numbers
Filter by multiple ni numbers
Filter by multiple payroll periods
Response
Orders retrieved successfully
Example response
{
"success": true,
"orders": [
{
"id": 1,
"client_id": "partner-client-id",
"employee_id": "EMP123",
"title": "Mr",
"first_name": "John",
"surname": "Doe",
"email": "john.doe@example.com",
"user_id": 1,
"effective_date": "2025-01-01T00:00:00Z",
"dispatch_date": "2025-01-02T00:00:00Z",
"total_amount_to_recover": "1200.0",
"total_end_of_agreement_inc_vat": "1200.0",
"amount_per_pay_period": "100.0",
"total_existing_active_orders_value": 1800,
"nmw_for_this_age_bracket": "6.4",
"order_number": 1,
"duration": 12,
"benefit_type": "Home and Electronics",
"benefit_name": "Home and Electronics / My Organisation",
"mobile_number": "07123456789",
"address1": "123 Main St",
"address2": "Suite 101",
"city": "London",
"county": "Greater London",
"postcode": "W1A 1AA",
"ni_number": "QQ123456C",
"date_of_birth": "1985-01-01",
"job_title": "Software Engineer",
"job_location": "Head Office",
"job_grade": "Band 5",
"partner_user_identifier": "ABC123",
"approval_status": "Accepted",
"order_status": "Order authorised",
"order_management_order_status": "Active",
"enabled": true,
"national_minimum_wage_check_complete": true,
"basic_details_check_complete": true,
"products": [
{
"ItemNo": "SKU123",
"ItemName": "MacBook Pro",
"ItemDescription": "16-inch Apple laptop",
"ItemQty": 1,
"ItemValue": 1200,
"ItemImage": "https://example.com/images/macbook_pro.jpg"
}
],
"comments": [
{
"name": "John Admin",
"comment": "The employee cancelled the order because",
"partner_user_id": "ABC123",
"created_at": "2025-01-10T14:30:00Z",
"comment_sent_to_employee": true
}
]
}
],
"scheme_types_by_count": {
"All": 2,
"Home and Electronics(home_and_electronics)": 1,
"Cycle to Work(cycle_to_work)": 1
}
}Changes
No recorded changes to this operation across all 1 revision of this API.