Get Voucher Program
GEThttps://api.uber.com/v1/organizations/{organization_id}/voucher-programs/{voucher_program_id}
¶ Use Case
The Get Voucher Program endpoint allows you to get voucher program details.
¶ Authorization
The Get Voucher Program endpoint requires an access_token using the client credentials
grant to organizations.voucher_programs
scope or using authorization_code
to organizations.voucher_programs.delegated
scope.
If an application follows third party authentication, this endpoint requires organizations.voucher_programs.aggregator
scope with the grant type as client_credentials
.
¶ Path Parameters
Name | Type | Optional | Description |
---|---|---|---|
organization_id |
string | No | Identifier for the organization the developer is part of and the entity that owns this voucher program. Should be known to developer when their organization was onboarded to Uber For Business. |
voucher_program_id |
string | No | The voucher_program_id returned back in the create voucher program call which identifies the voucher program created. |
¶ Request Parameters
Name | Type | Optional | Description |
---|---|---|---|
include_guests |
bool | Yes | Defaults to FALSE; if this field is not explicitly passed as TRUE then the guests object will be excluded from the response. |
¶ Response Fields
Name | Type | Optional | Description |
---|---|---|---|
name | string | No | Name of the voucher program |
currency_code | string | No | Currency of the offer value (in ISO 4217 format) |
pickup_locations | list | Yes | List of pickup location structs where each location struct is defined as: longitude - float latitude - float radius - int (meters) address - string (validation happens on latitude, longitude, and radius but address is displayed to the users) This is mandatory if the location_policy_type is defined as PICKUP_OR_DROPOFF, PICKUP_AND_DROPOFF, or PICKUP_ONLY |
dropoff_locations | list | Yes | List of dropoff location structs where each location struct is defined as: longitude - float latitude - float radius - int (meters) address - string (validation happens on latitude, longitude, and radius but address is displayed to the users) This is mandatory if the location_policy_type is defined as PICKUP_OR_DROPOFF, PICKUP_AND_DROPOFF, or DROPOFF_ONLY |
trip_restriction_type | string | Yes | This can be set to 4 string values below. PICKUP_OR_DROPOFF -. Restrict voucher program trips to start from the pickup or end from the dropoff. Both pickup and dropoff params need to be populated for this otherwise an error is thrown. PICKUP_AND_DROPOFF - Restrict voucher program trips to start from the pickup and end from the dropoff. Both pickup and dropoff params need to be populated for this otherwise an error is thrown. PICKUP_ONLY - Trips must start from one of the pickup locations passed in. If no pickup locations are given an error message will be thrown. DROPOFF_ONLY - Trips must end in one of the dropoff locations. If no dropoff locations are given then an error message will be thrown. Note: If pickup or dropoff are populated and the restrict_trip is not populated or has an incorrect value, an error message will be thrown. |
starts_at | int | No | Time when voucher program starts. Will be given as milliseconds since Unix Epoch. |
ends_at | int | Yes | Time when voucher program ends. Will be given as milliseconds since Unix Epoch. |
timezone | string | Yes | Timezone of the voucher program. List of valid timezones as input can be seen under the ‘TZ’ column here, https://en.wikipedia.org/wiki/List_of_tz_database_time_zone. If no Timezone is set, the default timezone of UTC will be used and returned back in the get call. |
max_trips_per_client | int | Yes | Maximum number of trips a guest can take on a voucher program that was applied to their uber account This field will be deprecated soon, please use ‘value_per_period_max_amount’ |
max_value_per_trip | float | Yes | Maximum value of a trip, a guest can take on a voucher program. This field will be deprecated soon, please use ‘value_per_trip_max_amount’ |
description | string | Yes | Any metadata a developer wants to attach to the voucher program |
code_scheme | string | No | An enum string specifying the scheme used for generating redemption codes/links for the voucher program. Possible values are:
|
expense_memo | string | Yes | A field used for data attribution on the voucher program and its resulting trips. Trips taken on offer generated from this voucher program will have this expense memo attached to them in CSV’s/trip views |
is_disabled | boolean | No | Indicates if this voucher program is active or not, will be set to true if the cancel voucher program endpoint is called. |
usage_trip_count | long | Yes | Indicates how many trips happened in this voucher program so far |
usage_voucher_claim_count | long | Yes | Indicates how many vouchers have been claimed for this voucher program so far |
usage_amount | double | Yes | The total amount of money that has been charged in this voucher program so far |
usage_amount_currency | string | Yes | The currency code of the usage amount (in iso 4217 format) |
value_per_trip_max_amount | float | No | Maximum dollar amount each voucher can cover on each trip fare. |
value_per_trip_deductible | float | Yes | Dollar amount of the trip fare that will be charged to the rider before being charged to the voucher issuer. |
value_per_trip_percentage | int | Yes | Percentage of the trip fare that will be charged to the voucher issuer. |
value_recurrence_period | string | Yes | Unit specifying the recurrence period of each voucher’s trip or credit allowance. The default value is ‘SINGLE’, which means no recurrence. Can be set to ‘DAILY’ or ‘MONTHLY’. |
value_per_period_max_credit | float | Yes | Maximum number of trips a rider can take, per period, on vouchers under this program. |
value_per_period_max_trips | int | Yes | Maximum amount of dollar credit that can be redeemed on a each voucher under this program, per period. |
vehicle_category_types | list<string> | Yes | A list of vehicle categories specifies the vehicle category types allowed on a voucher trip. If this field is empty, there are no restrictions on vehicle types for the trip. Possible values are one or combinations of the enum strings below: PREMIUM The premium vehicle category includes Black,Black SUV ECONOMY The economy vehicle category includes UberX and UberXL SHARED_RIDES The sharing vehicle category includes Pool |
voucher_type | string | Yes | Specifies the product the voucher can be used for. Possible values are one of the below: PERSONAL_TRANSPORT Voucher used for Uber Rides EATS Voucher used for Uber Eats GENERIC_VOUCHER Voucher used for Uber Rides or Uber Eats |
status | string | Yes | Status value [Upcoming, Active, Complete, Canceled] |
total_dollar_exposure | float | Yes | Program Total dollar exposure |
guests | list<object> | Yes | List of guests for a given voucher program |
guests[].email | string | Yes | Email for guest |
guests[].phone | string | Yes | Phone No. for guest |
¶ Example Request
curl -H 'Authorization: Bearer <TOKEN>' \
-H 'Accept-Language: en_US' \
-H 'Content-Type: application/json' \
'https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>?include_guests'
¶ Example Response
Status-Code: 200 OK
{
"name":"Uber Adventures",
"description":"Uber adventures provides a free trip to your upcoming adventure.",
"currency_Code":"USD",
"timezone":"America/Los_Angeles",
"organization_id":"d52621ce-149e-49f7-b7a1-3f5378fb752f",
"created_timestamp":1503704500,
"pickup_locations":[
{
"latitude":37.7754007824,
"longitude":-122.4174374020,
"radius":100,
"address":"1455 Market St, San Francisco, CA 94103, US"
}
],
"dropoff_locations":[
{
"latitude":37.7754007824,
"longitude":-122.4174374020,
"radius":100,
"address":"1455 Market St, San Francisco, CA 94103, US"
}
],
"trip_restriction_type":"PICKUP_OR_DROPOFF",
"starts_at":1503705500,
"ends_at":1606705500,
"max_trips_per_client":2,
"max_value_per_trip":50,
"code_scheme":"SINGLE_CODE_MULTI_REDEEM",
"redemptions_per_code":50,
"expense_memo":null,
"number_of_codes":null,
"is_disabled":false,
"usage_redeem_count":1,
"usage_amount":27.93,
"usage_amount_currency":"USD",
"usage_trip_count":2,
"value_per_period_max_trips":2,
"value_per_period_max_amount":20.23,
"value_recurrence_period":"MONTHLY",
"value_per_trip_deductible":10.11,
"value_per_trip_percentage":60,
"value_per_trip_max_amount":20.12,
"vehicle_category_types":[
"ECONOMY"
],
"voucher_type":"PERSONAL_TRANSPORT",
"status":"COMPLETE",
"total_dollar_exposure": 1000.0,
"guests": [
{
"email": "foo@bar.com"
},
{
"phone": "+1-123-456-7890"
}
]
}
¶ Error Responses
HTTP Status | Code | Description |
---|---|---|
400 | invalid_request |
This request is invalid |
403 | user_not_allowed |
User is not authorized for api access |
403 | unauthorized |
Requester not allowed to perform requested action. When the third party app (3P) is not authorized by the U4B organization |
404 | resource_not_found |
Voucher program is not found |
500 | internal_server_error |
We have experienced a problem |