Uber Developers

Update Voucher Program

PATCHhttps://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 Update Voucher Program endpoint allows you to update voucher program.

Note: voucher programs that have been canceled can not be updated. To see if a voucher program is canceled, you can call the Get Voucher Program endpoint and look at the status field.

¶ Authorization

The Update 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
name	string	Yes	Name of the voucher program (shown to riders).
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. 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	Yes	Time when voucher program starts. Should be given as milliseconds since Unix Epoch. This field can only be updated if the voucher program has not started.
ends_at	int	Yes	Time when voucher program ends. Should be given as milliseconds since Unix Epoch. This cannot be reduced if the voucher program has already started. Note: Any live, scheduled or completed voucher program can be extended by passing in a future ends_at time. This does not apply to canceled campaigns.
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.
redemptions_per_code	int	Yes	Number of times a code can be redeemed. This can be updated only if the code_scheme is SINGLE_CODE_MULTI_REDEEM. This field can only be increased when the voucher program has started.
expense_memo	string	Yes	A field used for data attribution on the voucher program and its resulting trips. Trips taken on vouchers generated from this voucher program will have this expense memo attached to them in CSV’s/trip views
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_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 can only be increased once the program has started.
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. This field can only be increased once the program has started. It can be updated only if it is present in the current voucher program.
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]. This field can only be increased once the program has started. It can be updated only if it is present in the current voucher program.
value_per_period_max_trips	int	Yes	Maximum number of trips a rider can take, per period, on vouchers under this program. This field can only be increased once the program has started. It can be updated only if it is present in the current voucher program.
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. This field can only be increased once the program has started. It can be updated only if it is present in the current voucher program.
vehicle_category_types	list<string>	Yes	A list of vehicle categories specifies the vehicle category types allowed on a voucher trip. If this list is empty, the existing vehicle type restrictions will be removed. This field can only be updated only if the program has not been started. 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

¶ Response Fields

Name	Type	Description
Void	null	Assume success when no error is returned back

¶ Example Request

curl -H 'Authorization: Bearer <TOKEN>' \
     -H 'Accept-Language: en_US' \
     -H 'Content-Type: application/json' \
     -X PATCH "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>"
     -d '{
      "name": "api campaign0701",
      "trip_restriction_type":"PICKUP_ONLY",
      "timezone": "America/Los_Angeles",
      "dropoff_locations":[{"longitude":-122.4174374020,"latitude":37.7754007824,"radius":25, "address": "1455 Market St, San Francisco, CA 94103, US"}],
      "pickup_locations":[{"longitude":-122.4174374020,"latitude":37.7754007824,"radius":25, "address": "1455 Market St, San Francisco, CA 94103, US"}],
      "starts_at": 1606605500,
      "ends_at": 1606705500,
      "redemptions_per_code": 10,
      "expense_memo":"memo-updated",
      "value_recurrence_period": "MONTHLY",
      "value_per_period_max_trips": 2,
      "value_per_period_max_amount":20.23,
      "value_per_trip_deductible": 10.11,
      "value_per_trip_percentage": 60,
      "value_per_trip_max_amount":20.12,
      "vehicle_category_types":[]
     }'

¶ Example Response

Status-Code: 204 No Content

¶ 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