Three lines

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

Uber

Developers
© 2023 Uber Technologies Inc.