Your IP : 216.73.216.1
<?php
/**
* Pinterest API V5 class
*
* @class Pinterest_For_Woocommerce_API
* @version 1.4.2
* @package Pinterest_For_WordPress/Classes/
*/
namespace Automattic\WooCommerce\Pinterest\API;
use Automattic\WooCommerce\Pinterest\PinterestApiException;
use Exception;
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* API V5 Methods
*/
class APIV5 extends Base {
const API_DOMAIN = 'https://api.pinterest.com/v5';
/**
* Prepare request
*
* @param string $endpoint the endpoint to perform the request on.
* @param string $method eg, POST, GET, PUT etc.
* @param array $payload Payload to be sent on the request's body.
* @param string $api The specific Endpoints subset.
*
* @return array
*/
public static function prepare_request( $endpoint, $method = 'POST', $payload = array(), $api = '' ) {
return array(
'url' => static::API_DOMAIN . "/{$endpoint}",
'method' => $method,
'args' => ! empty( $payload ) ? wp_json_encode( $payload ) : array(),
'headers' => array(
'Pinterest-Woocommerce-Version' => PINTEREST_FOR_WOOCOMMERCE_VERSION,
'Content-Type' => 'application/json',
),
'data_format' => 'body',
);
}
/**
* Returns basic user information.
*
* @since 1.4.0
*
* @return mixed|array {
* User account object.
*
* @type string $account_type Type of account. Enum: "PINNER" "BUSINESS".
* @type string $profile_image
* @type string $website_url
* @type string $username
* @type string $business_name
* @type int $board_count User account board count.
* @type int $pin_count User account pin count. This includes both created and saved pins.
* @type int $follower_count User account follower count.
* @type int $following_count User account following count.
* @type int $monthly_views User account monthly views.
* }
* @throws PinterestApiException Throws 403 and 500 exceptions.
*/
public static function get_account_info() {
return self::make_request( 'user_account', 'GET' );
}
/**
* Pull ads supported countries information from the API.
*
* @since 1.4.0
*
* @return array {
* Ad Accounts countries
*
* @type array[] $items {
* @type string $code Country ID from ISO 3166-1 alpha-2.
* @type string $currency Country currency.
* @type int $index Country index
* @type string $name Country name.
* }
* }
* @throws PinterestApiException If API request ends up other than 2xx status.
*/
public static function get_list_of_ads_supported_countries(): array {
$request_url = 'resources/ad_account_countries';
return self::make_request( $request_url, 'GET', array(), '', 2 * DAY_IN_SECONDS );
}
/**
* Returns the list of the user's websites.
*
* @since 1.4.0
*
* @return array {
* User account websites.
*
* @type array[] $items {
* @type string $website Website with path or domain only
* @type string $status Status of the verification process
* @type string $verified_at UTC timestamp when the verification happened - sometimes missing
* }
* @type string $bookmark
* }
* @throws PinterestApiException Throws 403 and 500 exceptions.
*/
public static function get_user_websites() {
return self::make_request( 'user_account/websites', 'GET' );
}
/**
* Returns the list of linked businesses.
*
* @since 1.4.0
*
* @return mixed|array[] {
* Linked businesses list.
*
* @type string $username
* @type string $image_small_url
* @type string $image_medium_url
* @type string $image_large_url
* @type string $image_xlarge_url
* }
* @throws PinterestApiException Throws 500 exception in case of unexpected error.
*/
public static function get_linked_businesses() {
return self::make_request( 'user_account/businesses', 'GET' );
}
/**
* Get the advertiser object from the Pinterest API for the given User ID.
*
* @since 1.4.0
*
* @param string $pinterest_user The Pinterest User ID.
*
* @return mixed
*/
public static function get_advertisers( $pinterest_user = null ) {
return self::make_request( 'ad_accounts', 'GET' );
}
/**
* Get the advertiser's tracking tags.
*
* @param string $ad_account_id the advertiser_id to request the tags for.
*
* @return array {
* Tag objects list.
*
* @type array[] $items {
* Tag object.
*
* @type string $ad_account_id Ad account ID.
* @type string $code_snippet Tag code snippet.
* @type ?string $enhanced_match_status The enhanced match status of the tag.
* @type string $id Tag ID.
* @type ?int $last_fired_time_ms Time for the last event fired.
*
* @type string $name Conversion tag name.
* @type string $status Entity status.
* @type string $version Version number.
* @type array $configs {
* Tag Enhanced Match configuration.
*
* @type ?bool $aem_enabled Whether Automatic Enhanced Match email is enabled.
* @type ?int $md_frequency Metadata ingestion frequency.
* @type ?bool $aem_fnln_enabled Whether Automatic Enhanced Match first name and last name is enabled.
* @type ?bool $aem_ph_enabled Whether Automatic Enhanced Match phone is enabled.
* @type ?bool $aem_ge_enabled Whether Automatic Enhanced Match gender is enabled.
* @type ?bool $aem_db_enabled Whether Automatic Enhanced Match birthdate is enabled.
* @type ?bool $aem_loc_enabled Whether Automatic Enhanced Match location is enabled.
* }
* }
* }
*
* @throws PinterestApiException|Exception Throws 500 exception.
*/
public static function get_advertiser_tags( $ad_account_id ) {
return self::make_request( "ad_accounts/{$ad_account_id}/conversion_tags", 'GET' );
}
/**
* Get the advertiser's tracking tag config and details.
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/conversion_tags/get
*
* @since 1.4.0
*
* @param string $ad_account_id Ad account ID.
* @param string $conversion_tag_id Conversion tag ID.
*
* @return mixed|array {
* Tag object.
*
* @type string $ad_account_id Ad account ID.
* @type string $code_snippet Tag code snippet.
* @type string $enhanced_match_status Enum: "UNKNOWN" "NOT_VALIDATED" "VALIDATING_IN_PROGRESS" "VALIDATION_COMPLETE" null
* The enhanced match status of the tag
* @type string $id Tag ID.
* @type int $last_fired_time_ms Time for the last event fired.
* @type string $name Conversion tag name.
* @type string $status Enum: "ACTIVE" "PAUSED" "ARCHIVED"
* Entity status
* @type string $version Version number.
* @type array $configs {
* Tag Enhanced Match configuration.
*
* @type bool $aem_enabled Whether Automatic Enhanced Match email is enabled.
* @type int $md_frequency Metadata ingestion frequency.
* @type bool $aem_fnln_enabled Whether Automatic Enhanced Match name is enabled.
* @type bool $aem_ph_enabled Whether Automatic Enhanced Match phone is enabled.
* @type bool $aem_ge_enabled Whether Automatic Enhanced Match gender is enabled.
* @type bool $aem_db_enabled Whether Automatic Enhanced Match birthdate is enabled.
* @type bool $aem_loc_enabled Whether Automatic Enhanced Match location is enabled.
* }
* }
* @throws PinterestApiException Throws 500 exception in case of unexpected error.
*/
public static function get_advertiser_tag( $ad_account_id, $conversion_tag_id ) {
return self::make_request( "ad_accounts/{$ad_account_id}/conversion_tags/{$conversion_tag_id}", 'GET' );
}
/**
* Create a tag for the given advertiser.
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/conversion_tags/create
*
* @since 1.4.0
*
* @param string $ad_account_id the advertiser_id to create a tag for.
*
* @return array {
* Tag object.
*
* @type string $ad_account_id Ad account ID.
* @type string $code_snippet Tag code snippet.
* @type ?string $enhanced_match_status The enhanced match status of the tag.
* @type string $id Tag ID.
* @type ?int $last_fired_time_ms Time for the last event fired.
* @type string $name Conversion tag name.
* @type string $status Entity status.
* @type string $version Version number.
* @type array $configs {
* Tag configuration.
*
* @type ?bool $aem_enabled Whether Automatic Enhanced Match email is enabled.
* @type ?int $md_frequency Metadata ingestion frequency.
* @type ?bool $aem_fnln_enabled Whether Automatic Enhanced Match name is enabled.
* @type ?bool $aem_ph_enabled Whether Automatic Enhanced Match phone is enabled.
* @type ?bool $aem_ge_enabled Whether Automatic Enhanced Match gender is enabled.
* @type ?bool $aem_db_enabled Whether Automatic Enhanced Match birthdate is enabled.
* @type ?bool $aem_loc_enabled Whether Automatic Enhanced Match location is enabled.
* }
* }
* @throws PinterestApiException|Exception Throws 500 exception.
*/
public static function create_tag( $ad_account_id ) {
$tag_name = self::get_tag_name();
return self::make_request(
"ad_accounts/{$ad_account_id}/conversion_tags",
'POST',
array(
'name' => $tag_name,
'aem_enabled' => true,
'md_frequency' => 1,
'aem_fnln_enabled' => true,
'aem_ph_enabled' => true,
'aem_ge_enabled' => true,
'aem_db_enabled' => true,
'ae_loc_enabled' => true,
)
);
}
/**
* Returns Pinterest user verification code for website verification.
*
* @since 1.4.0
*
* @return array {
* Data needed to verify a website.
*
* @type string $verification_code Code to check against the user claiming the website.
* @type string $dns_txt_record DNS TXT record to check against for the website to be claimed.
* @type string $metatag META tag the verification process searches for the website to be claimed.
* @type string $filename File expected to find on the website being claimed.
* @type string $file_content A full html file to upload to the website in order for it to be claimed.
* }
* @throws PinterestApiException If the request fails with 403 or 500 status.
*/
public static function domain_verification_data(): array {
return self::make_request( 'user_account/websites/verification', 'GET' );
}
/**
* Sends domain verification request to Pinterest.
*
* @since 1.4.0
*
* @param string $domain Domain to verify.
* @return array {
* Data returned by Pinterest after the verification request.
*
* @type string $website Website with path or domain only.
* @type string $status Status of the verification process.
* @type string $verified_at UTC timestamp when the verification happened - sometimes missing.
* }
* @throws PinterestApiException If the request fails with 2xx status.
*/
public static function domain_metatag_verification_request( string $domain ): array {
return self::make_request(
'user_account/websites',
'POST',
array(
'website' => $domain,
'verification_method' => 'METATAG',
)
);
}
/**
* Retrieves Commerce Integration.
*
* @param string $external_business_id WooCommerce's External Business ID (an autogenerated identifier of a customer).
* @return array {
* Integration data returned by Pinterest.
*
* @type string $id ID of the integration (string all digits).
* @type string $external_business_id External business ID for the integration.
* @type string $connected_merchant_id Connected merchant ID for the integration.
* @type string $connected_user_id Connected user ID for the integration.
* @type string $connected_advertiser_id Connected advertiser ID for the integration.
* @type string $connected_lba_id Connected LBA ID for the integration.
* @type string $connected_tag_id Connected tag ID for the integration.
* @type int $partner_access_token_expiry Partner access token expiry for the integration.
* @type int $partner_refresh_token_expiry Partner refresh token expiry for the integration.
* @type string $scopes Scopes for the integration.
* @type int $created_timestamp Created timestamp for the integration.
* @type int $updated_timestamp Updated timestamp for the integration.
* @type string $additional_id_1 Additional ID 1 for the integration.
* @type string $partner_metadata Partner metadata for the integration.
* }
* @throws PinterestApiException If the request fails with other than 200 status.
* @link https://developers.pinterest.com/docs/api/v5/integrations_commerce-get
* @since 1.4.11
*/
public static function get_commerce_integration( string $external_business_id ): array {
return self::make_request(
"integrations/commerce/{$external_business_id}",
'GET',
);
}
/**
* Create commerce integration.
*
* @param array $integration_data {
* Commerce integration data.
*
* @type string $external_business_id External business ID for the integration.
* @type string $external_business_id External business ID for the integration.
* @type string $connected_merchant_id Connected merchant ID for the integration.
* @type string $connected_user_id Connected user ID for the integration.
* @type string $connected_advertiser_id Connected advertiser ID for the integration.
* @type string $connected_lba_id Connected LBA ID for the integration.
* @type string $connected_tag_id Connected tag ID for the integration.
* @type int $partner_access_token_expiry Partner access token expiry for the integration.
* @type int $partner_refresh_token_expiry Partner refresh token expiry for the integration.
* @type string $scopes Scopes for the integration.
* @type int $created_timestamp Created timestamp for the integration.
* @type int $updated_timestamp Updated timestamp for the integration.
* @type string $additional_id_1 Additional ID 1 for the integration.
* }
*
* @return array {
* Integration data returned by Pinterest.
*
* @type string $id ID of the integration (string all digits).
* @type string $external_business_id External business ID for the integration.
* @type string $connected_merchant_id Connected merchant ID for the integration.
* @type string $connected_user_id Connected user ID for the integration.
* @type string $connected_advertiser_id Connected advertiser ID for the integration.
* @type string $connected_lba_id Connected LBA ID for the integration.
* @type string $connected_tag_id Connected tag ID for the integration.
* @type int $partner_access_token_expiry Partner access token expiry for the integration.
* @type int $partner_refresh_token_expiry Partner refresh token expiry for the integration.
* @type string $scopes Scopes for the integration.
* @type int $created_timestamp Created timestamp for the integration.
* @type int $updated_timestamp Updated timestamp for the integration.
* @type string $additional_id_1 Additional ID 1 for the integration.
* @type string $partner_metadata Partner metadata for the integration.
* }
* @throws PinterestApiException If the request fails with other than 200 status.
* @link https://developers.pinterest.com/docs/api/v5/#operation/integrations_commerce/post
* @since 1.4.0
*/
public static function create_commerce_integration( array $integration_data ): array {
return self::make_request(
'integrations/commerce',
'POST',
$integration_data
);
}
/**
* Updates WC integration parameters with Pinterest.
*
* @since 1.4.0
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/integrations_commerce/patch
*
* @param string $external_business_id External business ID for the integration.
* @param array $data {
* Integration data to update with Pinterest.
*
* @type string $external_business_id External business ID for the integration.
* @type string $connected_merchant_id Connected merchant ID for the integration.
* @type string $connected_advertiser_id Connected advertiser ID for the integration.
* @type string $connected_lba_id Connected LBA ID for the integration.
* @type string $connected_tag_id Connected tag ID for the integration.
* @type string $partner_access_token Partner access token for the integration.
* @type string $partner_refresh_token Partner refresh token for the integration.
* @type string $partner_primary_email Partner primary email for the integration.
* @type int $partner_access_token_expiry Partner access token expiry for the integration.
* @type int $partner_refresh_token_expiry Partner refresh token expiry for the integration.
* @type string $scopes Scopes for the integration.
* @type string $additional_id_1 Additional ID 1 for the integration.
* @type string $partner_metadata Partner metadata for the integration.
* }
*
* @return array {
* Integration data returned by Pinterest.
*
* @type string $id ID of the integration (string all digits).
* @type string $external_business_id External business ID for the integration.
* @type string $connected_merchant_id Connected merchant ID for the integration.
* @type string $connected_user_id Connected user ID for the integration.
* @type string $connected_advertiser_id Connected advertiser ID for the integration.
* @type string $connected_lba_id Connected LBA ID for the integration.
* @type string $connected_tag_id Connected tag ID for the integration.
* @type int $partner_access_token_expiry Partner access token expiry for the integration.
* @type int $partner_refresh_token_expiry Partner refresh token expiry for the integration.
* @type string $scopes Scopes for the integration.
* @type int $created_timestamp Created timestamp for the integration.
* @type int $updated_timestamp Updated timestamp for the integration.
* @type string $additional_id_1 Additional ID 1 for the integration.
* @type string $partner_metadata Partner metadata for the integration.
* }
* @throws PinterestApiException In case of 404, 409 and 500 errors from Pinterest.
*/
public static function update_commerce_integration( string $external_business_id, array $data ): array {
return self::make_request(
"integrations/commerce/{$external_business_id}",
'PATCH',
$data
);
}
/**
* Delete commerce integration.
*
* @since 1.4.0
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/integrations_commerce/del
*
* @param string $external_business_id External Business ID.
* @return array
* @throws PinterestApiException If the request fails with other than 204 status.
*/
public static function delete_commerce_integration( string $external_business_id ) {
return self::make_request(
"integrations/commerce/{$external_business_id}",
'DELETE'
);
}
/**
* Sends create feed request to Pinterest API.
*
* @since 1.4.0
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/feeds/create
*
* @param array $data {
* Feed data.
*
* @type string $name A human-friendly name associated to a given feed. This value is currently nullable due to historical reasons. It is expected to become non-nullable in the future.
* @type string $format The file format of a feed: TSV, CSV, XML.
* @type string $location The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing.
* @type string $catalog_type Type of the catalog entity: RETAIL, HOTEL.
* @type string $default_currency Currency Codes from ISO 4217.
* @type string $default_locale The locale used within a feed for product descriptions.
* @type string $default_country Country ID from ISO 3166-1 alpha-2.
* @type string $default_availability Default availability for products in a feed.
* @type array[] $credentials {
* Use this if your feed file requires username and password.
*
* @type string $username The required password for downloading a feed.
* @type string $password The required username for downloading a feed.
* }
* @type array[] $preferred_processing_schedule {
* Optional daily processing schedule. Use this to configure the preferred time for processing a feed (otherwise random).
*
* @type string $time A time in format HH:MM with leading 0 (zero).
* @type string $timezone The timezone considered for the processing schedule time.
* }
* }
* @param string $ad_account_id Pinterest Ad Account ID.
*
* @return array
*
* @throws PinterestApiException If the request fail with other than 201 status.
*/
public static function create_feed( array $data, string $ad_account_id ): array {
return self::make_request(
"catalogs/feeds?ad_account_id={$ad_account_id}",
'POST',
$data
);
}
/**
* Sends delete feed request to Pinterest API.
*
* @param string $feed_id Feed ID.
* @param string $ad_account_id Pinterest Ad Account ID.
*
* @return array
* @throws PinterestApiException If the request fails with other than 204 status.
*/
public static function delete_feed( string $feed_id, string $ad_account_id ) {
return self::make_request(
"catalogs/feeds/{$feed_id}?ad_account_id={$ad_account_id}",
'DELETE'
);
}
/**
* Sends update feed request to Pinterest API.
*
* @since 1.4.0
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/feeds/update
*
* @param string $feed_id Feed ID.
* @param array $data Feed data.
* @param string $ad_account_id Pinterest Ad Account ID.
*
* @return array
* @throws PinterestApiException If the request fails with other than 200 status.
*/
public static function update_feed( string $feed_id, array $data, string $ad_account_id ): array {
return self::make_request(
"catalogs/feeds/{$feed_id}?ad_account_id={$ad_account_id}",
'PATCH',
$data
);
}
/**
* Get merchant's feeds.
*
* @since 1.4.0
*
* @param string $ad_account_id Pinterest Ad Account ID.
*
* @return array {
* List of feeds.
*
* @type array[] $items { Feeds.
* @type string $id Feed ID.
* @type string $name A human-friendly name associated to a given feed. This value is currently nullable due to historical reasons. It is expected to become non-nullable in the future.
* @type string $status ACTIVE, INACTIVE. Status for catalogs entities. Present in catalogs_feed values. When a feed is deleted, the response will inform DELETED as status.
* @type string $format The file format of a feed: TSV, CSV, XML.
* @type string $location The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing.
* @type string $created_at
* @type string $updated_at
* @type string $catalog_type Type of the catalog entity: RETAIL, HOTEL.
* @type array[] $credentials {
* Use this if your feed file requires username and password.
*
* @type string $username The required password for downloading a feed.
* @type string $password The required username for downloading a feed.
* }
* @type array[] $preferred_processing_schedule {
* Optional daily processing schedule. Use this to configure the preferred time for processing a feed (otherwise random).
*
* @type string $time A time in format HH:MM with leading 0 (zero).
* @type string $timezone The timezone considered for the processing schedule time.
* }
* @type string $default_currency Currency Codes from ISO 4217.
* @type string $default_locale The locale used within a feed for product descriptions.
* @type string $default_country Country ID from ISO 3166-1 alpha-2.
* @type string $default_availability Default availability for products in a feed.
* }
* @type string $bookmark Cursor used to fetch the next page of items
* }
* @throws PinterestApiException If the request fails with 2xx status.
*/
public static function get_feeds( string $ad_account_id ): array {
return self::make_request(
"catalogs/feeds?ad_account_id={$ad_account_id}",
'GET',
array(),
'',
MINUTE_IN_SECONDS
);
}
/**
* Invalidate the ad account's feeds cache.
*
* @since 1.4.0
*
* @param string $ad_account_id Ad Account ID.
*
* @return bool True if the cache was invalidated, false otherwise.
*/
public static function invalidate_feeds_cache( string $ad_account_id ): bool {
return self::invalidate_cached_response(
"catalogs/feeds?ad_account_id={$ad_account_id}",
'GET',
array(),
''
);
}
/**
* Get the latest workflow for the given feed.
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/feed_processing_results/list
*
* @param string $feed_id Feed ID.
* @param string $ad_account_id Pinterest Ad Account ID.
* @return array {
* Feed Processing Results.
*
* @type array[] $items {
* Feed processing results.
*
* @type string $id Feed Processing Results ID.
* @type string $status Feed Processing status. "COMPLETED", "COMPLETED_EARLY", "DISAPPROVED", etc.
* @type array $product_counts {
* Feed product counts.
*
* @type int $original Original product count.
* @type int $ingested Ingested product count.
* }
* @type array $ingestion_details {
* Processing details.
*
* @type array $errors {} Errors.
* @type array $info {} Info
* @type array $warnings {} Warnings.
* }
* @type array $validation_details {
* Validation details.
*
* @type array $errors {} Errors.
* @type array $warnings {} Warnings.
* }
* @type string $created_at Feed Processing Results creation time.
* @type string $updated_at Feed Processing Results update time.
* }
* @type string $bookmark Cursor used to fetch the next page of items
* }
*
* @throws PinterestApiException If the request fails with other than 2xx status.
* @since 1.4.0
*/
public static function get_feed_processing_results( $feed_id, $ad_account_id ): array {
return self::make_request(
"catalogs/feeds/{$feed_id}/processing_results?ad_account_id={$ad_account_id}&page_size=1",
'GET',
array(),
'',
MINUTE_IN_SECONDS
);
}
/**
* List item issues for a given processing result.
*
* @param string $feed_processing_result_id Feed Processing Results ID.
* @param int $limit Number of items to return.
* @return array {
* Items and their corresponding issues.
*
* @type array[] $items {
* @type int $item_number
* @type string $item_id
* @type array $errors {
* An array of errors where keys are error codes e.g. (DUPLICATE_PRODUCTS, AVAILABILITY_INVALID, etc.).
*
* @type ?string $attribute_name The name of the attribute that caused the error.
* @type ?string $provided_value The value of the attribute that caused the error.
* }
* @type array $warnings {
* An array of warnings where keys are warning codes e.g. (SHIPPING_INVALID, TAX_INVALID, etc.).
*
* @type ?string $attribute_name The name of the attribute that caused the warning.
* @type ?string $provided_value The value of the attribute that caused the warning.
* }
* }
* }
*
* @throws PinterestApiException If the request fails with other than 2xx status.
* @since 1.4.0
*/
public static function get_feed_processing_result_items_issues( string $feed_processing_result_id, $limit = 25 ): array {
return self::make_request(
"catalogs/processing_results/{$feed_processing_result_id}/item_issues?page_size={$limit}",
'GET'
);
}
/**
* Attempts to redeem the offer code for the given advertiser.
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/ads_credit/redeem
*
* @since 1.4.0
*
* @param string $ad_account_id Pinterest Ad Account ID.
* @param string $offer_code Offer code (hash).
*
* @return array {
* Credits redeem status.
*
* @type bool $success Whether the offer code was successfully redeemed or not.
* @type ?int $errorCode Error code type if error occurs.
* @type ?string $errorMessage Reason for failure.
* }
* @throws PinterestApiException When unable to redeem the offer code or any unexpected error occur.
*/
public static function redeem_ads_offer_code( string $ad_account_id, string $offer_code ): array {
return self::make_request(
"ad_accounts/{$ad_account_id}/ads_credit/redeem",
'POST',
array(
'offerCodeHash' => $offer_code,
'validateOnly' => false,
)
);
}
/**
* Get active billing profiles in the advertiser account.
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/billing_profiles/get
*
* @since 1.4.0
*
* @param string $ad_account_id Pinterest Ad Account ID.
*
* @return array {
* Billing profiles in the advertiser account.
*
* @type array[] $items {
* @type string $id Billing ID.
* @type string $card_type Type of the card ("UNKNOWN" "VISA" "MASTERCARD" "AMERICAN_EXPRESS"
* "DISCOVER" "ELO").
* @type string $status Status of the billing. ("UNSPECIFIED" "VALID" "INVALID" "PENDING"
* "DELETED" "SECONDARY" "PENDING_SECONDARY").
* @type string $advertiser_id Advertiser ID of the billing.
* @type string $payment_method_brand Brand of the payment method. ("UNKNOWN" "VISA" "MASTERCARD"
* "AMERICAN_EXPRESS" "DISCOVER" "SOFORT" "DINERS_CLUB" "ELO"
* "CARTE_BANCAIRE").
* }
* @type string $bookmark Cursor used to fetch the next page of items.
* }
* @throws PinterestApiException If the request fails with other than 2xx status.
*/
public static function get_active_billing_profiles( string $ad_account_id ): array {
return self::make_request(
"ad_accounts/{$ad_account_id}/billing_profiles?is_active=true",
'GET'
);
}
/**
* Returns the list of discounts applied to the account.
*
* @link https://developers.pinterest.com/docs/api/v5/#operation/ads_credits_discounts/get
*
* @since 1.4.0
*
* @param string $ad_account_id Pinterest Ad Account ID.
*
* @return array {
* The list of discounts applied to the account.
*
* @type array[] $items {
* @type bool $active True if the offer code is currently active.
* @type string $advertiser_id Advertiser ID the offer was applied to.
* @type int $discountInMicroCurrency The discount applied in the offer’s currency value.
* @type string $discountCurrency Currency value for the discount.
* @type string $title Human-readable title of the offer code.
* @type int $remainingDiscountInMicroCurrency The credits left to spend.
* }
* @type string $bookmark Cursor used to fetch the next page of items.
* }
* @throws PinterestApiException If the request fails with other than 2xx status.
*/
public static function get_ads_credit_discounts( string $ad_account_id ): array {
return self::make_request(
"ad_accounts/{$ad_account_id}/ads_credit/discounts?page_size=25",
'GET'
);
}
/**
* Pull ads supported countries information from the API.
*
* @since 1.4.4
*
* @return array {
* Contains the status and token details.
*
* @type string $status The status of the token exchange.
* @type array $data {
* Contains token details.
*
* @type string $access_token The access token for authentication.
* @type string $refresh_token The refresh token for acquiring a new access token.
* @type string $token_type Type of the token, usually "bearer".
* @type int $expires_in Time in seconds when the access token expires.
* @type int $refresh_token_expires_in Time in seconds when the refresh token expires.
* @type string $scope The scope for which the access token has permission.
* }
* }
* @throws PinterestApiException If the request fails with other than 2xx status.
*/
public static function exchange_token() {
$request_url = 'oauth/commerce_integrations/token/exchange/';
return self::make_request( $request_url );
}
/**
* Sends Conversions API event data to Pinterest.
*
* @since 1.4.4
*
* @param string $ad_account_id Ad Account ID.
* @param array $data Event data.
* @return array
* @throws PinterestApiException If the request fails with other than 2xx status.
*/
public static function send_conversions_api_event( string $ad_account_id, array $data ) {
return self::make_request(
"ad_accounts/{$ad_account_id}/events",
'POST',
array( 'data' => array( $data ) )
);
}
}