Three lines

Uber

Developers

Create Voucher Program

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

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 Create Voucher Program endpoint allows you to create a voucher program.

Authorization

The Create 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.
Request Parameters
Name Type Optional Description
name string No Name of the voucher program (shown to riders).
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) (minimum of 20 meters)

address - string (address is displayed to the users and is a mandatory field in location)

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) (minimum of 20 meters)

address - string (address is displayed to the users and is a mandatory field in location)

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. This will be a default value if trip_restriction_type is not provided

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.

starts_at int No Start time from epoch of the voucher program in milliseconds. Cannot be more than 1 year into the future. Cannot be more than 24 hours in the past.
ends_at int No Time when voucher program ends. Should be given as milliseconds since Unix Epoch. Cannot be more than 1 year into the future.
timezone string Yes Timezone of the voucher program start and end times. 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_trips’ instead. Maximum value that can be specified is 999.
max_value_per_trip float Yes Maximum value of a trip, a guest can take on an offer. This field will be deprecated soon, please use ‘value_per_trip_max_amount’ instead.
description string Yes Internal description of the voucher program (not shown to riders).
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.

number_of_codes int Yes Number of codes to be generated. Required if code_scheme is set to MULTI_CODE_SINGLE_REDEEM. Defaults to 1 and throws an error if value is not 1 and code_scheme is SINGLE_CODE_MULTI_REDEEM
redemptions_per_code int Yes Number of times a code can be redeemed. Required if code_scheme is set to SINGLE_CODE_MULTI_REDEEM. Defaults to 1 and throws an error if value is not 1 and code_scheme is MULTI_CODE_SINGLE_REDEEM
expense_memo string Yes

A field used for data attribution on the voucher program and its resulting trips.

Trips taken on offers generated from this voucher program will have this expense memo attached to them in CSV’s/trip views

value_per_period_max_credit float

Yes

Maximum amount of dollar credit that can be redeemed on a each voucher under this program, per period.

Required unless value_per_trip_max_amount is set.

Ex: If set to 100, currency_code set to USD, and value_recurrence_period set to ‘SINGLE’, then: each voucher under this program can be used to redeem up to $100 USD during the active window.

value_per_trip_max_amount float

Yes

Maximum dollar amount each voucher can cover on each trip fare. Any overage amount will be charged to the rider.

Required unless value_per_period_max_credit is set.

value_per_period_max_trips int

Yes

Maximum number of trips a rider can take, per period, on vouchers under this program.

CAN NOT be used with value_per_period_max_credit.

Ex: If set to 5 and value_recurrence_period is set to ‘SINGLE’, each rider can use a voucher under this program on 5 trips total. If value_recurrence_period is set to ‘MONTHLY, each rider can take 5 trips on this voucher each month. Maximum value that can be specified is 999.

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. The default value is 0. If this field is set,‘value_per_trip_percentage may not be set and defaults to 0.

Ex: If set to 2, and value_per_trip_max_amount is set to 30, the rider will be charged for the first $2 and the voucher issuer will be charged for the next $30. Any amount over $32 will also be charged to the rider.

value_per_trip_percentage int Yes

Percentage of the trip fare that will be charged to the voucher issuer. The range for this field is [5, 99]. The default value is one hundred. If this field is customized, value_per_trip_deductible is disallowed to set non-default values. If value_per_trip_max_amount is set, that value is respected over the percentage.

Ex: If set to 20, and value_per_trip_max_amount is set to 5 then: for a $10 fare, $2 will be charged to the voucher issuer. For a $30 fare, $5 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’.

Ex: If set to ‘SINGLE’ and value_per_period_max_credit is set to 50, then each voucher can be used redeem to $50 total during the active window.

Ex: If set to DAILY and value_per_period_max_trips is set to 5, then each rider can take 5 trips a day on vouchers under this program.

Ex: If set to MONTHLY and value_per_period_max_trips is set to 5, then each rider can take 5 trips a month on vouchers under this program.

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 not set with valid vehicle categories, there will be 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 and BlackSUV

ECONOMY

The economy vehicle category includes UberX and UberXL

SHARED_RIDES

The shared 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

If don't specify, defaulted to PERSONAL_TRANSPORT

creator_email string No

Email of the voucher campaign creator. This will be used to authorize the creator of campaigns against permissions set forth by the organization.

Response Fields
Name Type Description
voucher_program_id string voucher_program_id for the created voucher program. The caller needs to store this value.
code_text string Will be empty if the number of codes specified is greater than 1.
code_link string Will be empty if the number of codes specified is greater than 1.
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'
     -d '{
        "name": "Uber Adventures",
        "description": "Uber adventures provides a free trip to your upcoming adventure.",
        "currency_code": "USD",
        "timezone": "America/Los_Angeles",
        "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": 1620895738000,
        "ends_at": 1636885762000,
        "max_trips_per_client": 1,
        "max_value_per_trip": 50,
        "code_scheme": "SINGLE_CODE_MULTI_REDEEM",
        "redemptions_per_code": 10,
        "value_per_period_max_trips": 2,
        "value_per_period_max_credit":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"
      }'

Example Response

If the number of codes is equal to one:
Status-Code: 200 OK

{
  "voucher_program_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
  "code_text": "def-456",
  "code_link": "https://m.uber.com/?promotion_code=def-456"
}

If number of codes is greater than one:
Status-Code: 200 OK

{
  "voucher_program_id": "a1111c8c-c720-46c3-8534-2fcdd730040d"
}
Error Responses
HTTP Status Code Description
400 invalid_request This request is invalid
402 missing_payment_account The payment account for this organization needs to be set up first
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
500 internal_server_error We have experienced a problem

Uber

Developers
© 2023 Uber Technologies Inc.