Pinterest Credit API
The Credit API from Pinterest — 2 operation(s) for credit.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Credit API
description: This is the description of your API.
contact:
name: Pinterest, Inc.
url: https://developers.pinterest.com/
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Credit
paths:
/ad_accounts/{ad_account_id}/ads_credit/discounts:
get:
summary: Get ads credit discounts
description: 'Returns the list of discounts applied to the account.
<strong>This endpoint might not be available to all apps. <a href=''/docs/new/about-beta-access/''>Learn more</a>.</strong>'
operationId: ads_credits_discounts/get
security:
- pinterest_oauth2:
- ads:read
- billing:read
x-ratelimit-category: ads_read
x-sandbox: disabled
tags:
- Credit
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/AdsCreditDiscountsResponse'
description: Success
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/ad_accounts/{ad_account_id}/ads_credit/redeem:
post:
summary: Redeem ad credits
description: 'Redeem ads credit on behalf of the ad account id and apply it towards billing.
<strong>This endpoint might not be available to all apps. <a href=''/docs/new/about-beta-access/''>Learn more</a>.</strong>'
tags:
- Credit
operationId: ads_credit/redeem
security:
- pinterest_oauth2:
- ads:write
- billing:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
description: Redeem ad credits request.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdsCreditRedeemRequest'
responses:
'200':
description: Successfully redeemed ad credits.
content:
application/json:
schema:
$ref: '#/components/schemas/AdsCreditRedeemResponse'
'400':
description: Error thrown when unable to redeem offer code.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
ValidationError:
value:
code: 15
message: Unable to redeem offer code. Try again later.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
query_page_size:
name: page_size
description: Maximum number of items to include in a single page of the response. See documentation on <a href='/docs/getting-started/pagination/'>Pagination</a> for more information.
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 250
default: 25
query_bookmark:
name: bookmark
description: Cursor used to fetch the next page of items
in: query
required: false
schema:
type: string
path_ad_account_id:
name: ad_account_id
description: Unique identifier of an ad account.
in: path
required: true
schema:
type: string
pattern: ^\d+$
maxLength: 18
schemas:
AdsCreditRedeemResponse:
type: object
properties:
success:
description: Returns true if the offer code was successfully applied(validateOnly=false) or can be applied(validateOnly=true).
type: boolean
example: false
errorCode:
description: Error code type if error occurs
type: integer
nullable: true
example: 2708
errorMessage:
description: Reason for failure
type: string
nullable: true
example: The offer has already been redeemed by this advertiser
AdsCreditRedeemRequest:
type: object
required:
- offerCodeHash
- validateOnly
properties:
offerCodeHash:
description: Takes in a SHA256 hash of the offerCode.
example: 138e9e0ff7e38cf511b880975eb574c09aa9d5e1657590ab0431040da68caa67
type: string
pattern: ^[a-z0-9]*$
validateOnly:
description: If true, only validate if we can redeem offer code. Otherwise it will actually apply the offer code to the account
example: true
type: boolean
Error:
title: Error
type: object
properties:
code:
type: integer
message:
type: string
required:
- code
- message
Paginated:
type: object
properties:
items:
type: array
items:
type: object
bookmark:
type: string
nullable: true
required:
- items
AdsCreditDiscountsResponse:
type: object
properties:
active:
description: True if the offer code is currently active.
type: boolean
example: true
advertiser_id:
description: Advertiser ID the offer was applied to.
type: string
pattern: ^\d+$
example: '12312451231'
discountType:
description: The type of discount of this credit
type: string
nullable: true
enum:
- COUPON
- CREDIT
- COUPON_APPLIED
- CREDIT_APPLIED
- MARKETING_OFFER_CREDIT
- MARKETING_OFFER_CREDIT_APPLIED
- GOODWILL_CREDIT
- GOODWILL_CREDIT_APPLIED
- INTERNAL_CREDIT
- INTERNAL_CREDIT_APPLIED
- PREPAID_CREDIT
- PREPAID_CREDIT_APPLIED
- SALES_INCENTIVE_CREDIT
- SALES_INCENTIVE_CREDIT_APPLIED
- CREDIT_EXPIRED
- FUTURE_CREDIT
- REFERRAL_CREDIT
- INVOICE_SALES_INCENTIVE_CREDIT
- INVOICE_SALES_INCENTIVE_CREDIT_APPLIED
- PREPAID_CREDIT_REFUND
- null
discountInMicroCurrency:
description: The discount applied in the offers currency value.
type: number
nullable: true
example: 125000000
discountCurrency:
type: string
nullable: true
description: Currency value for the discount.
example: USD
title:
description: Human readable title of the offer code.
type: string
nullable: true
example: Ads Credits
remainingDiscountInMicroCurrency:
type: number
nullable: true
description: The credits left to spend.
example: 125000000
securitySchemes:
pinterest_oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://www.pinterest.com/oauth/
tokenUrl: https://api.pinterest.com/v5/oauth/token
scopes:
ads:read: See all of your advertising data, including ads, ad groups, campaigns etc.
ads:write: Create, update, or delete ads, ad groups, campaigns etc.
billing:read: See all of your billing data, billing profile, etc.
billing:write: Create, update, or delete billing data, billing profiles, etc.
biz_access:read: See business access data
biz_access:write: Create, update, or delete business access data
boards:read: See your public boards, including group boards you join
boards:read_secret: See your secret boards
boards:write: Create, update, or delete your public boards
boards:write_secret: Create, update, or delete your secret boards
catalogs:read: See all of your catalogs data
catalogs:write: Create, update, or delete your catalogs data
pins:read: See your public Pins
pins:read_secret: See your secret Pins
pins:write: Create, update, or delete your public Pins
pins:write_secret: Create, update, or delete your secret Pins
user_accounts:read: See your user accounts and followers
user_accounts:write: Update your user accounts and followers
conversion_token:
type: http
scheme: bearer
description: This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com).
basic:
type: http
scheme: basic
x-tagGroups:
- name: Pin and Boards
tags:
- pins
- boards
- media
- aggregated_comments
- aggregated_pin_data
- user_account
- name: Campaign Management
tags:
- ad_accounts
- campaigns
- ad_groups
- ads
- product_group_promotions
- bulk
- name: Targeting
tags:
- audiences
- customer_lists
- keywords
- targeting_template
- audience_insights
- audience_sharing
- name: Ad Formats
tags:
- lead_forms
- lead_ads
- leads_export
- name: Billing
tags:
- billing
- order_lines
- terms_of_service
- name: Business Access
tags:
- business_access_assets
- business_access_invite
- business_access_relationships
- name: Conversions
tags:
- conversion_events
- conversion_tags
- name: Others
tags:
- integrations
- oauth
- resources
- search
- terms
- name: Shopping
tags:
- catalogs
- name: Deprecated
tags:
- product_groups