Uber Developers

Create Voucher Program From Template

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

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 From Template endpoint allows you to create a voucher program using a predefined template.

¶ Authorization

The Create Voucher Program From Template 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
template_id	string	No	The template this campaign is based on
name	string	Yes	Name of the voucher program (shown to riders). If not provided, will use default provided in template
starts_at	int	No	Time when voucher program starts. Should be given as milliseconds since Unix Epoch. Cannot be more than 1 year into the future.
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.
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.
total_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
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
timing_restrictions	list<object>	Yes	( start_minute - [int] - Start of time window (from start of day, in minutes) end_minute - [int] - End of time window days_of_week - [list<int>] - Represents each day of the week that this restriction applies to )
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.
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
creator_email	string	Yes	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	Optional	Description
voucher_program_id	string	No	uuid of the created voucher program. The caller needs to store this value.
code_text	string	Yes	Will be empty if the number of codes specified is greater than 1.
code_link	string	Yes	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/create-from-template'
     -d '{
          "template_id": "abcx-adfa-3l2lk",
          "name": "Uber Adventures",
          "description": "Uber adventures provides a free trip to your upcoming adventure.",
          "timezone": "America/Los_Angeles",
          "starts_at": 1685641631000,
          "ends_at": 1688233631000,
          "code_scheme": "SINGLE_CODE_MULTI_REDEEM",
          "redemptions_per_code": 10,
          "timing_restrictions": [
            {
              "start_minute": 0,
              "end_minute": 1440,
              "days_of_week": [1,2,3,4,5]
            }
          ],
          "trip_restriction_type": "PICKUP_AND_DROPOFF",
          "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"
          }],
          "creator_email": "<creator_email>"
        }'

¶ Example Response

When 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"
}

When a field is passed which was not in the template Status-Code: 400

{
  "message": "This request is invalid. Cannot override the following: currency_code, value_per_trip_deductible"
}

When a required field is not in the template nor is it provided in the request Status-Code: 400

{
  "message": "This request is invalid. The following field(s) are required: redemptions_per_code"
}

¶ Error Responses

HTTP Status	Code	Description
400	`invalid_request`	This request is invalid
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 template is not found
500	`internal_server_error`	We have experienced a problem