Uber Developers

Get Voucher Program

GEThttps://api.uber.com/v1/organizations/{organization_id}/voucher-programs/{voucher_program_id}

Privileged and Confidential This endpoint design has been confidentially shared with you. It is still under development and is subject to change without notice. Please do not share this document or API endpoint details with anyone who is not authorized to have access. For more information read about scopes.

¶ 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: SINGLE_CODE_MULTI_REDEEM A single code will be generated. It will be able to be redeemed by up to redemptions_per_code riders. MULTI_CODE_SINGLE_REDEEM The number of codes generated will be equal to the number_of_codes parameter. Each code will be able to be redeemed once, by a single rider.
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