Partager via

Objet de données InsertionOrder - Facturation client

  • Article

Un ordre d’insertion est un contrat qui établit le montant maximal que vous allez dépenser sur votre compte sur une période spécifiée. Si vous avez configuré la facturation mensuelle pour votre compte, vous devez disposer d’un ordre d’insertion actif pour que vos annonces soient éligibles à la livraison. Vous contrôlez toujours vos dépenses à l’aide de votre budget de campagne, et vous serez facturé uniquement pour ce que vous accumulez. Par exemple, si vous aviez une commande d’insertion d’un mois de 5 000 $ et que vous n’avez accumulé que 4 500 $ de frais au cours de la période de facturation, nous ne déduirons que 4 500 $ du budget de votre commande d’insertion.

Avertissement

Le budget de l’ordre d’insertion s’applique uniquement aux dépenses publicitaires, ce qui est une distinction importante si votre entreprise se trouve dans un pays/une région où services en ligne sont taxées. Si vous avez une limite budgétaire stricte, vous devrez peut-être tenir compte des taxes dans votre budget d’ordre d’insertion. Pour en savoir plus sur les exigences fiscales de votre entreprise, consultez l’article d’aide Informations sur les taxes ou la TVA .

La plupart des éléments de cet objet ne peuvent être définis qu’avant l’approbation de l’ordre d’insertion, c’est-à-dire si l’état est défini sur PendingUserReview. Dans ce cas, vous pouvez apporter de nouvelles modifications ou approuver ou refuser l’ordre d’insertion via des éléments de cet objet. Une fois que l’état de l’ordre d’insertion est Actif, Épuisé, Expiré ou Nondémarré, vous pouvez apporter de nouvelles modifications ou approuver ou refuser les modifications en attente actuelles via l’élément PendingChanges . Si l’état de l’ordre d’insertion est Annulé ou Refusé, vous ne pouvez pas mettre à jour l’ordre d’insertion.

Remarque

L’opération SearchInsertionOrders retourne jusqu’à 24 ordres d’insertion par série périodique.

Vous pouvez récupérer mais, à de très rares exceptions près, vous ne pouvez pas ajouter ou mettre à jour une série d’ordres d’insertion via l’API Bing Ads. Utilisez l’élément IsInSeries pour déterminer si l’ordre d’insertion se trouve dans une série périodique.

  • Si vous tentez de mettre à jour startdate ou endDate d’un ordre d’insertion faisant partie d’une série périodique, l’API retourne une erreur.
  • Si vous mettez à jour l’état d’un ordre d’insertion faisant partie d’une série périodique, la mise à jour status est appliquée à toutes les commandes d’insertion de la série.

Pour gérer les commandes d’insertion périodiques dans l’application web Microsoft Advertising, consultez l’article d’aide Comment faire créer et modifier un ordre d’insertion ?

Syntaxe

<xs:complexType name="InsertionOrder" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:sequence>
    <xs:element minOccurs="0" name="AccountId" type="xs:long" />
    <xs:element minOccurs="0" name="BookingCountryCode" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Comment" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="EndDate" nillable="true" type="xs:dateTime" />
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="LastModifiedByUserId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="LastModifiedTime" nillable="true" type="xs:dateTime" />
    <xs:element minOccurs="0" name="NotificationThreshold" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="ReferenceId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="SpendCapAmount" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="StartDate" nillable="true" type="xs:dateTime" />
    <xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Status" nillable="true" type="tns:InsertionOrderStatus" />
    <xs:element minOccurs="0" name="PurchaseOrder" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="PendingChanges" nillable="true" type="tns:InsertionOrderPendingChanges" />
    <xs:element minOccurs="0" name="AccountNumber" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="BudgetRemaining" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="BudgetSpent" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="BudgetRemainingPercent" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="BudgetSpentPercent" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="SeriesName" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="IsInSeries" nillable="true" type="xs:boolean" />
    <xs:element minOccurs="0" name="SeriesFrequencyType" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="IsUnlimited" nillable="true" type="xs:boolean">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="IsEndless" nillable="true" type="xs:boolean">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
  </xs:sequence>
</xs:complexType>

Éléments

L’objet InsertionOrder contient les éléments suivants : AccountId, AccountNumber, BookingCountryCode, BudgetRemaining, BudgetRemainingPercent, BudgetSpent, BudgetSpentPercent, Comment, EndDate, Id, IsEndless, IsInSeries, IsUnlimited, LastModifiedByUserId, LastModifiedTime, Name, NotificationThreshold, PendingChanges, PurchaseOrder, ReferenceId, SeriesFrequencyType, SeriesName, SpendCapAmount, StartDate, Status.

Élément Description Type de données
AccountId Identificateur du compte auquel s’applique l’ordre d’insertion.

Vous ne pouvez pas mettre à jour l’identificateur du compte après avoir créé l’ordre d’insertion.

Ajouter: Obligatoire
Mettre à jour: En lecture seule		 long
Numéro de compte Numéro de compte généré par le système utilisé pour identifier le compte dans l’application web Microsoft Advertising. Le numéro de compte a la forme xxxxxxxx, où xxxxxxxx est une série de huit caractères alphanumériques.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 chaîne
BookingCountryCode Réservé à une utilisation interne.

Ajouter: Obligatoire pour certains comptes ; Facultatif pour certains comptes.
Mettre à jour: En lecture seule		 chaîne
BudgetRemaining Solde d’exécution de l’ordre d’insertion.

La valeur de solde en cours d’exécution est initialement identique à celle de SpendCapAmount, puis diminue chaque fois qu’une publicité est servie dans le compte.

Cet élément est vide si l’ordre d’insertion a un budget illimité.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 double
BudgetRemainingPercent Pourcentage de budget restant pour l’ordre d’insertion.

Cette valeur est calculée en tant que BudgetRemaining / SpendCapAmount.

Cet élément est vide si l’ordre d’insertion a un budget illimité.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 double
BudgetSpent Solde restant de l’ordre d’insertion.

Le solde restant est initialement égal à 0 (zéro), puis augmente vers spendCapAmount chaque fois qu’une annonce dans le compte est servie.

Cet élément est vide si l’ordre d’insertion a un budget illimité.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 double
BudgetSpentPercent Pourcentage du budget dépensé pour l’ordre d’insertion.

Cette valeur est calculée en tant que BudgetSpent / SpendCapAmount.

Cet élément est vide si l’ordre d’insertion a un budget illimité.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 double
Commentaire Description de l’ordre d’insertion. La description est limitée à 100 caractères.

Ajouter: Optionnel
Mettre à jour: Optionnel		 chaîne
EndDate Date d’expiration de l’ordre d’insertion. La date de fin doit être postérieure à la date de début.

La date est stockée en temps universel coordonné (UTC). Seuls le mois, le jour et l’année de la chaîne spécifiée sont utilisés. Si vous spécifiez l’heure, les minutes et les secondes d’une date, ils seront ignorés.

Pour plus d’informations sur le format de la date et de l’heure, consultez l’entrée dateTime dans Types de données XML primitifs.

Remarque : Si l’ordre d’insertion n’a pas de date de fin, EndDate est vide. L’ajout ou la mise à jour d’ordres d’insertion illimités n’est pas pris en charge. EndDate fonctionne en mode lecture seule.

Ajouter: Obligatoire
Mettre à jour: Optionnel. Si vous tentez de mettre à jour startdate ou endDate d’un ordre d’insertion faisant partie d’une série périodique , l’API retourne une erreur.		 dateTime
Id Identificateur généré par le système qui identifie l’ordre d’insertion.

Ajouter: En lecture seule
Mettre à jour: Lecture seule et Obligatoire		 long
IsEndless Détermine si l’ordre d’insertion n’a pas de date de fin.

Si la valeur est True, l’ordre d’insertion n’a pas de date de fin et la date de fin de cet ordre d’insertion est ignorée.

Ajouter: Optionnel
Mettre à jour: Optionnel		 boolean
IsInSeries Détermine si l’ordre d’insertion se trouve dans une série périodique.

Si la valeur est True, l’ordre d’insertion fait partie d’une série périodique. Si vous tentez de mettre à jour startdate ou endDate d’un ordre d’insertion faisant partie d’une série périodique, l’API retourne une erreur. Si vous mettez à jour l’état d’un ordre d’insertion faisant partie d’une série périodique, la mise à jour status est appliquée à toutes les commandes d’insertion de la série.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 boolean
IsUnlimited Détermine si l’ordre d’insertion a un budget illimité.

Si la valeur est True, l’ordre d’insertion aura un budget illimité et le SpendCapAmount de cet ordre d’insertion sera ignoré.

Ajouter: Optionnel
Mettre à jour: Optionnel		 boolean
LastModifiedByUserId Identificateur du dernier utilisateur à mettre à jour l’ordre d’insertion.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 long
LastModifiedTime Date et heure de la dernière mise à jour de l’ordre d’insertion.

La date est stockée en temps universel coordonné (UTC).

Pour plus d’informations sur le format de la date et de l’heure, consultez l’entrée dateTime dans Types de données XML primitifs.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 dateTime
Nom Nom convivial qui peut être utilisé pour référencer cet ordre d’insertion.

Le nom peut contenir un maximum de 100 caractères.

Le nom n’a pas besoin d’être unique par rapport à d’autres commandes d’insertion pour le client.

Ajouter: Optionnel
Mettre à jour: Optionnel		 chaîne
NotificationThreshold Pourcentage du budget qui a été dépensé. Spécifiez le pourcentage sous la forme d’une valeur comprise entre 0 et 100. Une notification est envoyée lorsque le seuil est atteint. Par exemple, si vous définissez le seuil sur 70, le service de facturation envoie une notification lorsque vous avez dépensé 70 % du budget.

Si vous ne souhaitez pas recevoir de notification, définissez sur NULL.

Réservé à une utilisation interne.

Ajouter: Optionnel
Mettre à jour: Optionnel		 double
PendingChanges Peut être utilisé pour gérer les modifications d’un ordre d’insertion approuvé avec status défini sur Actif, Épuisé, Expiré ou Nondémarré.

Ajouter: En lecture seule
Mettre à jour: Optionnel		 InsertionOrderPendingChanges
PurchaseOrder Valeur de bon de commande qui peut être utilisée pour référencer cet ordre d’insertion dans des factures mensuelles. Cette valeur est imprimée en tant que bon de commande dans les factures mensuelles.

Le bon de commande peut contenir un maximum de 50 caractères.

Ajouter: Optionnel
Mettre à jour: Optionnel		 chaîne
ReferenceId Réservé à une utilisation interne.

Ajouter: Optionnel
Mettre à jour: Optionnel		 long
SeriesFrequencyType Détermine la façon dont une commande est récurrence dans la série.

Les valeurs possibles sont Monthly, BiMonthly, Quarterly et Annuel.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 chaîne
SeriesName Nom de la série d’ordres d’insertion périodique.

Le nom peut contenir un maximum de 100 caractères.

Même si l’ordre d’insertion est supprimé ultérieurement de la série périodique, cet élément continue de refléter le nom de la série dans laquelle il a été créé.

Ajouter: En lecture seule
Mettre à jour: En lecture seule		 chaîne
SpendCapAmount Budget de cet ordre d’insertion. Le budget est une limite difficile. Lorsque le compte atteint cette limite et qu’aucun autre ordre d’insertion n’est disponible, la valeur du cycle de vie du compte status est définie sur Pause.

Cet élément est vide si l’ordre d’insertion a un budget illimité. Le budget correspond au montant maximal que vous souhaitez dépenser pour un ordre d’insertion. Pour les commandes d’insertion avec un budget illimité, votre budget est limité par votre limite de crédit. Dans ce cas, le budget quotidien de chaque campagne détermine les dépenses maximales.

Remarque : L’ajout ou la mise à jour d’ordres d’insertion illimités n’est pas pris en charge. SpendCapAmount fonctionne en mode lecture seule.

Ajouter: Obligatoire
Mettre à jour: Optionnel		 double
StartDate Date à laquelle l’ordre d’insertion peut commencer à accumuler des frais. La date de début doit être ultérieure à la date actuelle.

La date est stockée en temps universel coordonné (UTC). Seuls le mois, le jour et l’année de la chaîne spécifiée sont utilisés. Si vous spécifiez l’heure, les minutes et les secondes d’une date, ils seront ignorés.

Pour plus d’informations sur le format de la date et de l’heure, consultez l’entrée dateTime dans Types de données XML primitifs.

Ajouter: Obligatoire
Mettre à jour: Optionnel. Vous pouvez uniquement mettre à jour la date de début via cet élément si l’état est PendingUserReview. Si la date de début est déjà dépassée, vous ne pouvez pas la modifier.

Si vous tentez de mettre à jour startdate ou endDate d’un ordre d’insertion faisant partie d’une série périodique , l’API retourne une erreur.		 dateTime
Statut Status de l’ordre d’insertion.

Ajouter: En lecture seule. Les ordres d’insertion que vous créez sont immédiatement définis sur Actif, Nondémarré ou Refusé.
Mettre à jour: Requis pour approuver ou refuser une commande d’insertion qui n’est pas encore approuvée, ou annuler une commande d’insertion qui a déjà été approuvée. Vous ne pouvez approuver ou refuser via cet élément que si le status actuel est défini sur PendingUserReview. Vous ne pouvez annuler via cet élément que si le status actuel est défini sur Actif, Épuisé ou NotStarted. Une fois que l’ordre d’insertion status est Actif, Épuisé, Expiré ou NotStarted, vous pouvez apporter de nouvelles modifications ou approuver ou refuser les modifications en attente actuelles via l’élément PendingChanges.

Lorsque vous appelez UpdateInsertionOrder, vous pouvez définir cet élément Status ou modifier d’autres éléments de cet objet, mais vous ne pouvez pas modifier le status en parallèle avec d’autres mises à jour de propriétés.

Si vous mettez à jour l’état d’une commande d’insertion faisant partie d’une série périodique, la mise à jour status est appliquée à toutes les commandes d’insertion de la série.		 InsertionOrderStatus

Configuration requise

Service : CustomerBillingService.svc v13
Namespace: https://bingads.microsoft.com/Customer/v13/Entities

Utilisé par

AddInsertionOrder
SearchInsertionOrders
UpdateInsertionOrder