Create Voucher Template
POSThttps://api.uber.com/v1/organizations/{organization_id}/voucher-program-templates¶ Use Case
The Create Voucher Template endpoint allows you to create a voucher template.
¶ Authorization
The Create Voucher 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 your organization. |
¶ Request Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| template_name | string | No | Name of the voucher template. |
| campaign_name | string | Yes | Default Name of the voucher program (shown to riders). |
| 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. |
| currency_code | string | Yes | Currency of the offer value (in ISO 4217 format) |
| is_fully_covered | boolean | Yes | True if trips are fully covered |
| 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. This field is required unless value_per_period_max_credit is set, in which case it will be set to value_per_period_max_credit. value_per_period_max_trips is a dependent field and MUST be provided if value_per_trip_max_amount is specified. |
| 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. |
| value_per_period_max_trips | int | Yes | Maximum number of trips a rider can take, per period, on vouchers under this program. If this field is set, value_per_period_max_credit may not be set. 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_period_max_credit | float | Yes | Maximum amount of dollar credit that can be redeemed on a each voucher under this program, per period. If this field is set, value_per_period_max_trips may not be set. The currency that this amount is set in is defined by the currency_code field. 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. |
| 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 | No | 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 |
| 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 | No | Email of the voucher campaign template creator. This will be used to authorize creation against permissions set forth by the organization. |
¶ Response Fields
| Name | Type | Description |
|---|---|---|
| uuid | string | unique id for the created voucher template. The caller needs to store this value. |
¶ 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-program-templates'
-d '{
"template_name": "Uber Grand Adventures Template",
"name": "Uber Adventures",
"timezone": "America/Los_Angeles",
"currency_code": "USD",
"is_fully_covered": false,
"value_per_period_max_credit": 20.23,
"value_recurrence_period": "MONTHLY",
"value_per_trip_percentage": 60,
"vehicle_category_types": ["PREMIUM"],
"creator_email": "<creator_email>",
"voucher_type": "PERSONAL_TRANSPORT",
"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"
}]
}'
¶ Example Response
Status-Code: 200 OK
{
"uuid": "a1111c8c-c720-46c3-8534-2fcdd730040d"
}
¶ 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 |
| 500 | internal_server_error |
We have experienced a problem |